Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(execd): replace uploads atomically so a failed write keeps the old file

Jason Cat97bca01a4885
diff --git a/components/execd/pkg/web/controller/file_owner_other.go b/components/execd/pkg/web/controller/file_owner_other.go
new file mode 100644
index 000000000..e73bd0636
--- /dev/null
+++ b/components/execd/pkg/web/controller/file_owner_other.go
@@ -0,0 +1,25 @@
+//go:build !unix
+
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controller
+
+import "os"
+
+// copyFileOwnership is a no-op where the platform exposes no numeric owner and
+// group on a FileInfo.
+func copyFileOwnership(string, os.FileInfo) error {
+ return nil
+}
diff --git a/components/execd/pkg/web/controller/file_owner_unix.go b/components/execd/pkg/web/controller/file_owner_unix.go
new file mode 100644
index 000000000..9a2d1ffaf
--- /dev/null
+++ b/components/execd/pkg/web/controller/file_owner_unix.go
@@ -0,0 +1,37 @@
+//go:build unix
+
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controller
+
+import (
+ "fmt"
+ "os"
+ "syscall"
+)
+
+// copyFileOwnership records the owner and group of info on path, so staging a
+// file and renaming it over an existing one keeps the ownership an in-place
+// write preserved.
+func copyFileOwnership(path string, info os.FileInfo) error {
+ stat, ok := info.Sys().(*syscall.Stat_t)
+ if !ok {
+ return nil
+ }
+ if err := os.Chown(path, int(stat.Uid), int(stat.Gid)); err != nil {
+ return fmt.Errorf("chown %s to %d:%d: %w", path, stat.Uid, stat.Gid, err)
+ }
+ return nil
+}
diff --git a/components/execd/pkg/web/controller/filesystem_upload.go b/components/execd/pkg/web/controller/filesystem_upload.go
index 72229b7f9..7acbc9d00 100644
--- a/components/execd/pkg/web/controller/filesystem_upload.go
+++ b/components/execd/pkg/web/controller/filesystem_upload.go
@@ -15,9 +15,13 @@
package controller
import (
+ "crypto/rand"
+ "encoding/hex"
"encoding/json"
+ "errors"
"fmt"
"io"
+ "io/fs"
"mime/multipart"
"net/http"
"os"
@@ -173,35 +177,108 @@ func writeUploadFile(resolvedPath string, fileHeader *multipart.FileHeader) *upl
}
defer file.Close()
- dst, err := os.OpenFile(resolvedPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.ModePerm)
- if err != nil {
+ return writeUploadStream(resolvedPath, file)
+}
+
+// uploadTempPattern prefixes the staging file an upload writes next to its
+// destination. The leading dot keeps it out of a plain directory listing.
+const uploadTempPattern = ".osb-upload-"
+
+// maxUploadSymlinkDepth bounds the final-component symlink walk; it mirrors the
+// kernel's ELOOP threshold closely enough to reject a link cycle.
+const maxUploadSymlinkDepth = 40
+
+// writeUploadStream replaces target with the bytes read from r.
+//
+// The bytes are staged in this directory and renamed into place only once they
+// are fully written and synced, so a write that fails partway - ENOSPC, an I/O
+// error, the daemon being killed mid-copy - leaves the file it was replacing
+// intact. An in-place O_TRUNC write destroyed it, and a sandbox usually holds
+// the only copy of the file an upload overwrites.
+func writeUploadStream(target string, r io.Reader) *uploadError {
+ resolvedTarget, uerr := resolveUploadTargetPath(target)
+ if uerr != nil {
+ return uerr
+ }
+
+ existing, statErr := os.Stat(resolvedTarget)
+ switch {
+ case statErr == nil && !existing.Mode().IsRegular():
+ // A device or a FIFO cannot be staged and renamed over without being
+ // replaced by a regular file, so keep refusing them as before.
return newUploadError(
http.StatusInternalServerError,
model.ErrorCodeRuntimeError,
- fmt.Sprintf("error opening destination file %s. %v", resolvedPath, err),
+ fmt.Sprintf("error opening destination file %s. not a regular file", resolvedTarget),
+ )
+ case statErr == nil:
+ // A rename only needs a writable directory, so probe the file itself to
+ // keep rejecting a read-only destination the way an in-place write did.
+ probe, err := os.OpenFile(resolvedTarget, os.O_WRONLY, 0)
+ if err != nil {
+ return newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error opening destination file %s. %v", resolvedTarget, err),
+ )
+ }
+ _ = probe.Close()
+ case !errors.Is(statErr, fs.ErrNotExist):
+ return newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error opening destination file %s. %v", resolvedTarget, statErr),
)
}
- if _, err := io.Copy(dst, file); err != nil {
- dst.Close()
+ tmp, err := createUploadTemp(filepath.Dir(resolvedTarget))
+ if err != nil {
return newUploadError(
http.StatusInternalServerError,
model.ErrorCodeRuntimeError,
- fmt.Sprintf("error copying file %s. %v", resolvedPath, err),
+ fmt.Sprintf("error creating the upload staging file for %s. %v", resolvedTarget, err),
)
}
+ tmpName := tmp.Name()
+ committed := false
+ defer func() {
+ if committed {
+ return
+ }
+ _ = tmp.Close()
+ _ = os.Remove(tmpName)
+ }()
+
+ if statErr == nil {
+ // An in-place write kept the metadata of the file it overwrote: carry
+ // the mode over, and the owner/group where the platform exposes them,
+ // so replacing the file does not change who can read or write it.
+ if err := tmp.Chmod(existing.Mode().Perm()); err != nil {
+ return uploadWriteError(resolvedTarget, err)
+ }
+ if err := copyFileOwnership(tmpName, existing); err != nil {
+ log.Warn("upload: preserve owner/group of %s: %v", resolvedTarget, err)
+ }
+ }
- if err := dst.Sync(); err != nil {
+ if _, err := io.Copy(tmp, r); err != nil {
+ return uploadWriteError(resolvedTarget, err)
+ }
+ if err := tmp.Sync(); err != nil {
log.Error("upload: sync target file: %v", err)
}
- if err := dst.Close(); err != nil {
- log.Error("upload: close target file: %v", err)
+ if err := tmp.Close(); err != nil {
+ return uploadWriteError(resolvedTarget, err)
}
+ if err := os.Rename(tmpName, resolvedTarget); err != nil {
+ return uploadWriteError(resolvedTarget, err)
+ }
+ committed = true
// fsync parent directory so the new dirent is durable and visible on
// weakly-coherent filesystems (virtio-fs, 9pfs, etc.). Best-effort:
// some filesystems return ENOTSUP for directory fsync.
- targetDir := filepath.Dir(resolvedPath)
+ targetDir := filepath.Dir(resolvedTarget)
if d, err := os.Open(targetDir); err == nil {
if err := d.Sync(); err != nil {
log.Warn("upload: sync parent dir %s: %v", targetDir, err)
@@ -211,6 +288,76 @@ func writeUploadFile(resolvedPath string, fileHeader *multipart.FileHeader) *upl
return nil
}
+func uploadWriteError(path string, err error) *uploadError {
+ return newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error writing file %s. %v", path, err),
+ )
+}
+
+// createUploadTemp creates the staging file with the mode a plain create in
+// this directory has today (os.ModePerm masked by the umask), so a client that
+// sends no permission keeps the mode it used to get.
+func createUploadTemp(dir string) (*os.File, error) {
+ var suffix [8]byte
+ for attempt := 0; attempt < 10; attempt++ {
+ if _, err := rand.Read(suffix[:]); err != nil {
+ return nil, err
+ }
+ name := filepath.Join(dir, uploadTempPattern+hex.EncodeToString(suffix[:]))
+ f, err := os.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, os.ModePerm)
+ if err == nil {
+ return f, nil
+ }
+ if !errors.Is(err, fs.ErrExist) {
+ return nil, err
+ }
+ }
+ return nil, errors.New("could not allocate a unique staging file name")
+}
+
+// resolveUploadTargetPath follows a symlink in the final path component, so the
+// rename replaces the file an in-place write would have written through the
+// link instead of replacing the link itself.
+func resolveUploadTargetPath(path string) (string, *uploadError) {
+ resolved := path
+ for i := 0; i < maxUploadSymlinkDepth; i++ {
+ info, err := os.Lstat(resolved)
+ if err != nil {
+ if errors.Is(err, fs.ErrNotExist) {
+ // A new file, or the target of a dangling link.
+ return resolved, nil
+ }
+ return "", newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error resolving destination file %s. %v", path, err),
+ )
+ }
+ if info.Mode()&os.ModeSymlink == 0 {
+ return resolved, nil
+ }
+ link, err := os.Readlink(resolved)
+ if err != nil {
+ return "", newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error resolving destination symlink %s. %v", resolved, err),
+ )
+ }
+ if !filepath.IsAbs(link) {
+ link = filepath.Join(filepath.Dir(resolved), link)
+ }
+ resolved = link
+ }
+ return "", newUploadError(
+ http.StatusInternalServerError,
+ model.ErrorCodeRuntimeError,
+ fmt.Sprintf("error resolving destination file %s. too many levels of symbolic links", path),
+ )
+}
+
// applyUploadPermission applies the metadata permission with one retry to
// absorb metadata-propagation delay on weakly-coherent filesystems
// (virtio-fs, 9pfs). ChmodFile always invokes chown under the hood, so a
diff --git a/components/execd/pkg/web/controller/filesystem_upload_atomic_test.go b/components/execd/pkg/web/controller/filesystem_upload_atomic_test.go
new file mode 100644
index 000000000..3e170df59
--- /dev/null
+++ b/components/execd/pkg/web/controller/filesystem_upload_atomic_test.go
@@ -0,0 +1,143 @@
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controller
+
+import (
+ "bytes"
+ "errors"
+ "mime/multipart"
+ "net/http"
+ "os"
+ "path/filepath"
+ "runtime"
+ "testing"
+ "testing/iotest"
+
+ "github.com/stretchr/testify/require"
+)
+
+// requireNoUploadStaging asserts the staging file of a failed upload is gone.
+func requireNoUploadStaging(t *testing.T, dir string) {
+ t.Helper()
+ entries, err := os.ReadDir(dir)
+ require.NoError(t, err)
+ for _, entry := range entries {
+ require.NotContainsf(t, entry.Name(), uploadTempPattern, "staging file %s was left behind", entry.Name())
+ }
+}
+
+// A copy that fails after the destination was opened must not cost the sandbox
+// the file it was replacing: the upload fails and the old content survives.
+func TestWriteUploadStreamFailureKeepsTheReplacedFile(t *testing.T) {
+ dir := t.TempDir()
+ target := filepath.Join(dir, "notes.md")
+ original := []byte("previous content\n")
+ require.NoError(t, os.WriteFile(target, original, 0o640))
+
+ uerr := writeUploadStream(target, iotest.ErrReader(errors.New("source failed mid-copy")))
+
+ require.NotNil(t, uerr)
+ got, err := os.ReadFile(target)
+ require.NoError(t, err)
+ require.Equal(t, string(original), string(got))
+ if runtime.GOOS != "windows" {
+ info, err := os.Stat(target)
+ require.NoError(t, err)
+ require.Equal(t, os.FileMode(0o640), info.Mode().Perm(),
+ "an in-place write kept the destination mode; a staged replace must keep it too")
+ }
+ requireNoUploadStaging(t, dir)
+}
+
+func TestWriteUploadStreamFailureLeavesNoNewFile(t *testing.T) {
+ dir := t.TempDir()
+ target := filepath.Join(dir, "absent.txt")
+
+ uerr := writeUploadStream(target, iotest.ErrReader(errors.New("source failed mid-copy")))
+
+ require.NotNil(t, uerr)
+ _, err := os.Stat(target)
+ require.ErrorIs(t, err, os.ErrNotExist)
+ requireNoUploadStaging(t, dir)
+}
+
+func TestWriteUploadStreamReplacesContent(t *testing.T) {
+ dir := t.TempDir()
+ target := filepath.Join(dir, "notes.md")
+ require.NoError(t, os.WriteFile(target, []byte("old"), 0o644))
+
+ uerr := writeUploadStream(target, bytes.NewReader([]byte("new content")))
+
+ require.Nil(t, uerr)
+ got, err := os.ReadFile(target)
+ require.NoError(t, err)
+ require.Equal(t, "new content", string(got))
+ requireNoUploadStaging(t, dir)
+}
+
+// An upload to a symlinked path keeps writing the link target, as an in-place
+// write did, instead of replacing the link with a regular file.
+func TestWriteUploadStreamFollowsSymlinkTarget(t *testing.T) {
+ dir := t.TempDir()
+ realFile := filepath.Join(dir, "real.txt")
+ link := filepath.Join(dir, "current")
+ require.NoError(t, os.WriteFile(realFile, []byte("old"), 0o644))
+ if err := os.Symlink(realFile, link); err != nil {
+ t.Skipf("symlinks unavailable: %v", err)
+ }
+
+ uerr := writeUploadStream(link, bytes.NewReader([]byte("through the link")))
+
+ require.Nil(t, uerr)
+ info, err := os.Lstat(link)
+ require.NoError(t, err)
+ require.NotZero(t, info.Mode()&os.ModeSymlink, "the symlink itself must survive the replace")
+ got, err := os.ReadFile(realFile)
+ require.NoError(t, err)
+ require.Equal(t, "through the link", string(got))
+}
+
+// The multipart entry point keeps honoring the metadata path and mode.
+func TestUploadFileWritesThroughMultipart(t *testing.T) {
+ dir := t.TempDir()
+ target := filepath.Join(dir, "uploaded.txt")
+
+ body := &bytes.Buffer{}
+ writer := multipart.NewWriter(body)
+ metadata, err := writer.CreateFormFile("metadata", "metadata")
+ require.NoError(t, err)
+ _, err = metadata.Write([]byte(`{"path":"` + filepath.ToSlash(target) + `","mode":644}`))
+ require.NoError(t, err)
+ filePart, err := writer.CreateFormFile("file", "uploaded.txt")
+ require.NoError(t, err)
+ _, err = filePart.Write([]byte("multipart payload"))
+ require.NoError(t, err)
+ require.NoError(t, writer.Close())
+
+ ctrl, rec := newFilesystemController(t, http.MethodPost, "/files/upload", body.Bytes())
+ ctrl.ctx.Request.Header.Set("Content-Type", writer.FormDataContentType())
+ ctrl.UploadFile()
+
+ require.Equal(t, http.StatusOK, rec.Code)
+ got, err := os.ReadFile(target)
+ require.NoError(t, err)
+ require.Equal(t, "multipart payload", string(got))
+ if runtime.GOOS != "windows" {
+ info, err := os.Stat(target)
+ require.NoError(t, err)
+ require.Equal(t, os.FileMode(0o644), info.Mode().Perm())
+ }
+ requireNoUploadStaging(t, dir)
+}
diff --git a/docs/architecture/data-plane/execd.md b/docs/architecture/data-plane/execd.md
index 89dac5abf..00086485a 100644
--- a/docs/architecture/data-plane/execd.md
+++ b/docs/architecture/data-plane/execd.md
@@ -100,6 +100,8 @@ This is a sandbox-wide credential, not a restricted terminal ticket. Obtain it t
One API covers the whole filesystem tree: stream files in and out, list and search directories, inspect and change permissions, replace file contents, move and remove paths. The file APIs in every sandbox SDK are a thin wrapper over these endpoints.
+An upload replaces its destination only after the bytes are fully written and synced: a copy that fails partway leaves the file it was replacing untouched instead of truncating it. The replacement keeps the destination's mode and, on Unix, its owner and group.
+
### Filesystem execution identity
On Linux, a trusted backend can select the identity performing ordinary file operations by prefixing the file API path with `/v1/filesystem/{uid}/{gid}`. Both IDs are required decimal integers between 0 and 4294967294. For example, `GET /v1/filesystem/1001/1001/files/download?path=/workspace/session-b/result.txt` reads the file as UID 1001 with primary GID 1001. The same prefix supports all ordinary file and directory operations, including uploads, metadata, search, replacement, rename, deletion, and permission changes.