Skip to content

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

fix(egress): persist strict owner retirement fences

leo peinccad27b4c23d
diff --git a/components/egress/fastsandbox.go b/components/egress/fastsandbox.go
index ad2aa6338..4f33caf48 100644
--- a/components/egress/fastsandbox.go
+++ b/components/egress/fastsandbox.go
@@ -71,6 +71,9 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstream
if err != nil {
log.Fatalf("fast-sandbox Actions protocol: %v", err)
}
+ if err := validateOwnerDomain(os.Getenv(constants.EnvEgressPolicyDir), actionsAPIVersion); err != nil {
+ log.Fatalf("fast-sandbox Actions domain: %v", err)
+ }
otelShutdown, err := telemetry.Init(ctx)
if err != nil {
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.go
index 0a3c48170..61156e5e4 100644
--- a/components/egress/fastsandbox_actions.go
+++ b/components/egress/fastsandbox_actions.go
@@ -208,12 +208,51 @@ func (s *fastSandboxPolicyServer) handleActionsV2(w http.ResponseWriter, r *http
http.Error(w, "snapshot and state-transfer operations are not supported by Actions v2", http.StatusNotImplemented)
return
}
+ if env.Operation == actionhandler.OperationSetBinding && env.Binding.IsRemoval() {
+ http.Error(w, "live binding removal is unsupported; use Sandbox Delete", http.StatusNotImplemented)
+ return
+ }
+ record, err := s.readOwnerRecord(subj)
+ if err != nil {
+ http.Error(w, "owner persistence unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ if env.Operation == actionhandler.OperationRemoveBinding && record != nil && record.Phase == "retired" {
+ writeJSON(w, http.StatusOK, struct{}{})
+ return
+ }
+ if env.Operation == actionhandler.OperationSetBinding || env.Operation == actionhandler.OperationRemoveBinding {
+ phase := "active"
+ if env.Operation == actionhandler.OperationRemoveBinding {
+ phase = "retiring"
+ }
+ if err := s.writeOwnerRecord(subj, *env.Owner, phase); err != nil {
+ http.Error(w, err.Error(), http.StatusServiceUnavailable)
+ return
+ }
+ }
+ // An absent owner has no registered runtime to dispatch REMOVE to. Persist
+ // a terminal fence anyway, so a delayed initial SET cannot resurrect it.
+ if env.Operation == actionhandler.OperationRemoveBinding && record == nil {
+ if err := s.writeOwnerRecord(subj, *env.Owner, "retired"); err != nil {
+ http.Error(w, err.Error(), http.StatusServiceUnavailable)
+ return
+ }
+ writeJSON(w, http.StatusOK, struct{}{})
+ return
+ }
status, err := s.dispatchAction(r.Context(), env)
if err != nil {
logEgressUpdateFailedError(fmt.Sprintf("Actions v2 %s for sandbox %s failed: %v", env.Operation, env.Sandbox.UID, err))
http.Error(w, err.Error(), status)
return
}
+ if env.Operation == actionhandler.OperationRemoveBinding {
+ if err := s.writeOwnerRecord(subj, *env.Owner, "retired"); err != nil {
+ http.Error(w, err.Error(), http.StatusServiceUnavailable)
+ return
+ }
+ }
s.mu.Lock()
switch env.Operation {
case actionhandler.OperationSetBinding:
@@ -228,24 +267,23 @@ func (s *fastSandboxPolicyServer) handleActionsV2(w http.ResponseWriter, r *http
}
func (s *fastSandboxPolicyServer) validateActionsV2Owner(subj subject.Subject, env *actionhandler.Envelope) error {
- if env.Owner == nil || !env.Owner.Valid() || env.Owner.SandboxUID != env.Sandbox.UID ||
- env.Owner.RuntimeInstanceID != env.Revision.RuntimeInstanceID || env.Owner.AttachmentID != env.Revision.AttachmentID ||
- uint64(env.Owner.RouteGeneration) != env.Revision.RouteGeneration {
- return fmt.Errorf("Actions v2 owner does not match the Sandbox revision")
+ record, err := s.readOwnerRecord(subj)
+ if err != nil {
+ return err
}
- s.mu.Lock()
- defer s.mu.Unlock()
- current, found := s.actionOwners[subj]
- if !found {
- if env.Operation != actionhandler.OperationSetBinding {
- return fmt.Errorf("Actions v2 owner is not registered")
+ if record == nil {
+ if env.Operation != actionhandler.OperationSetBinding && env.Operation != actionhandler.OperationRemoveBinding {
+ return fmt.Errorf("strict owner is not registered")
}
- return nil
+ return s.cleanOwnerSubject(subj)
+ }
+ if !record.Owner.Matches(*env.Owner) {
+ return fmt.Errorf("strict owner mismatch; rebind is unsupported")
}
- if current.Matches(*env.Owner) {
- return nil
+ if record.Phase != "active" && env.Operation != actionhandler.OperationRemoveBinding {
+ return fmt.Errorf("strict owner is retiring or retired")
}
- return fmt.Errorf("Actions v2 owner mismatch")
+ return nil
}
func (s *fastSandboxPolicyServer) handleActionsV2Owner(w http.ResponseWriter, r *http.Request) {
@@ -257,55 +295,35 @@ func (s *fastSandboxPolicyServer) handleActionsV2Owner(w http.ResponseWriter, r
uid := strings.TrimPrefix(r.URL.Path, constants.ActionsV2OwnerPathPrefix)
owner, err := ownerFromRequest(r)
if !validVaultSubjectID(uid) || err != nil || owner.SandboxUID != uid {
- http.Error(w, "a valid owner matching the Sandbox UID is required", http.StatusBadRequest)
+ http.Error(w, "valid matching owner required", http.StatusBadRequest)
return
}
- ownerLock := s.ownerLock(subject.FromSandboxUID(uid))
- ownerLock.RLock()
- defer ownerLock.RUnlock()
- release, err := s.acquireAction(r.Context())
+ subj := subject.FromSandboxUID(uid)
+ lock := s.ownerLock(subj)
+ lock.RLock()
+ defer lock.RUnlock()
+ record, err := s.readOwnerRecord(subj)
if err != nil {
- http.Error(w, "owner observation canceled", http.StatusServiceUnavailable)
+ http.Error(w, "owner persistence unavailable", http.StatusServiceUnavailable)
return
}
- defer release()
- subj := subject.FromSandboxUID(uid)
- s.mu.Lock()
- current, ownerFound := s.actionOwners[subj]
- residual := s.subjectHasLiveStateLocked(subj)
- s.mu.Unlock()
- regFence, registered := s.reg.Fence(subj)
- if ownerFound {
- if !current.Matches(owner) {
- http.Error(w, "owner status is unknown or belongs to another owner", http.StatusConflict)
- return
- }
- if registered {
- if !regFence.Matches(subject.Fencing{RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID}) {
- http.Error(w, "registered fence disagrees with the Actions v2 owner", http.StatusConflict)
- return
- }
- writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "current", Owner: owner})
+ if record == nil {
+ if err := s.cleanOwnerSubject(subj); err != nil {
+ http.Error(w, err.Error(), http.StatusConflict)
return
}
- }
- if registered || residual {
- http.Error(w, "owner status is unknown; residual subject state exists", http.StatusConflict)
+ writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "absent", Owner: owner})
return
}
- residual, err = s.subjectHasPersistentState(subj)
- if err != nil || residual {
- http.Error(w, "owner retirement cannot be confirmed", http.StatusServiceUnavailable)
+ if !record.Owner.Matches(owner) {
+ http.Error(w, "owner mismatch", http.StatusConflict)
return
}
- if ownerFound {
- s.mu.Lock()
- if currentOwner, ok := s.actionOwners[subj]; ok && currentOwner.Matches(owner) {
- delete(s.actionOwners, subj)
- }
- s.mu.Unlock()
+ state := "current"
+ if record.Phase == "retired" {
+ state = "retired"
}
- writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "retired", Owner: owner})
+ writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: state, Owner: owner})
}
func (s *fastSandboxPolicyServer) subjectHasLiveStateLocked(subj subject.Subject) bool {
@@ -377,6 +395,11 @@ func (s *fastSandboxPolicyServer) validateRelayOwner(w http.ResponseWriter, r *h
return false
}
subj := subject.FromSandboxUID(uid)
+ record, recordErr := s.readOwnerRecord(subj)
+ if recordErr != nil || record == nil || record.Phase != "active" || !record.Owner.Matches(owner) {
+ http.Error(w, "strict owner is not active", http.StatusPreconditionFailed)
+ return false
+ }
s.mu.Lock()
current, found := s.actionOwners[subj]
s.mu.Unlock()
diff --git a/components/egress/fastsandbox_actions_v2_test.go b/components/egress/fastsandbox_actions_v2_test.go
index 25b9a1a72..e8347acc6 100644
--- a/components/egress/fastsandbox_actions_v2_test.go
+++ b/components/egress/fastsandbox_actions_v2_test.go
@@ -1,16 +1,33 @@
+// 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 main
import (
"encoding/base64"
"encoding/json"
+ "fmt"
"net/http"
"net/http/httptest"
"net/netip"
+ "path/filepath"
"strings"
"testing"
"github.com/alibaba/opensandbox/egress/pkg/actionhandler"
"github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
"github.com/alibaba/opensandbox/egress/pkg/subject"
"github.com/stretchr/testify/require"
)
@@ -25,6 +42,7 @@ func actionsV2Owner(uid, runtimeID, attachmentID string, generation int64) actio
func actionsV2Body(t *testing.T, operation actionhandler.Operation, owner actionhandler.Owner, input *string) string {
t.Helper()
env := actionhandler.Envelope{
+ Mode: "legacy",
APIVersion: actionhandler.APIVersionV2, Operation: operation, InvocationID: "v2-test",
Sandbox: actionhandler.SandboxRef{UID: owner.SandboxUID}, Owner: &owner,
Revision: actionhandler.Revision{SpecGeneration: 1, RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID, RouteGeneration: uint64(owner.RouteGeneration)},
@@ -123,7 +141,7 @@ func TestActionsV2SeparatesSubjectsAndFencesOwnerChanges(t *testing.T) {
require.True(t, gotB.Matches(b))
newOwnerABody := actionsV2Body(t, actionhandler.OperationSetBinding, newOwnerA, policyInput)
- require.Equal(t, http.StatusOK, doActionsV2(t, srv, newOwnerABody).Code)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, newOwnerABody).Code, "strict rebind requires a new Sandbox UID")
}
func TestActionsV2RejectsSnapshotAndRelayPathOwnerMismatchBeforeEffects(t *testing.T) {
@@ -135,6 +153,7 @@ func TestActionsV2RejectsSnapshotAndRelayPathOwnerMismatchBeforeEffects(t *testi
require.True(t, registeredBefore)
beforeDeny := len(nft.denyFirst)
snapshot, err := json.Marshal(actionhandler.Envelope{
+ Mode: "legacy",
APIVersion: actionhandler.APIVersionV2, Operation: actionhandler.OperationVaultExport, InvocationID: "snap",
Sandbox: actionhandler.SandboxRef{UID: "a"}, Revision: actionhandler.Revision{SpecGeneration: 1, RuntimeInstanceID: owner.RuntimeInstanceID, AttachmentID: owner.AttachmentID, RouteGeneration: 1},
Owner: &owner, Snapshot: &actionhandler.SnapshotTransfer{Path: "/tmp/state"},
@@ -198,3 +217,110 @@ func TestActionsV2CarriesOwnerThroughVaultAndPolicyRelayCRUD(t *testing.T) {
_, found := reg.Fence(subject.FromSandboxUID("b"))
require.False(t, found, "relay must not materialize an unbound subject")
}
+
+func TestActionsV2RequiresModeBeforeSideEffects(t *testing.T) {
+ for _, mode := range []string{"", "explicit", "unknown"} {
+ t.Run(mode, func(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ var body map[string]any
+ require.NoError(t, json.Unmarshal([]byte(actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())), &body))
+ body["mode"] = mode
+ raw, err := json.Marshal(body)
+ require.NoError(t, err)
+ require.Equal(t, http.StatusBadRequest, doActionsV2(t, srv, string(raw)).Code)
+ _, registered := reg.Fence(subject.FromSandboxUID("a"))
+ require.False(t, registered)
+ record, err := srv.readOwnerRecord(subject.FromSandboxUID("a"))
+ require.NoError(t, err)
+ require.Nil(t, record)
+ })
+ }
+}
+
+func TestActionsV2RetirementSurvivesRestartAndRejectsOldSet(t *testing.T) {
+ srv, _, _ := fastSandboxTestServer(t)
+ // Exercise actual atomic files, not just the in-memory file seam.
+ srv.policyFiles.newFile = func(path string) (vaultFileStore, error) { return policy.NewAtomicPolicyFile(path) }
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ set := actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())
+ remove := actionsV2Body(t, actionhandler.OperationRemoveBinding, owner, nil)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, set).Code)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, remove).Code)
+ require.FileExists(t, filepath.Join(srv.policyFiles.dir, "a.json.owner"))
+ require.Error(t, validateOwnerDomain(srv.policyFiles.dir, constants.ActionsAPIVersion))
+ require.NoError(t, validateOwnerDomain(srv.policyFiles.dir, constants.ActionsAPIVersionV2))
+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, set).Code)
+ restarted, reg, _ := fastSandboxTestServer(t)
+ restarted.SetPolicyFiles(srv.policyFiles)
+ restarted.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, restarted, set).Code)
+ require.Equal(t, http.StatusOK, doActionsV2(t, restarted, remove).Code)
+ observation := doActionsV2Relay(t, restarted, http.MethodGet, constants.ActionsV2OwnerPathPrefix+"a", owner, "")
+ require.Equal(t, http.StatusOK, observation.Code)
+ require.Contains(t, observation.Body.String(), `"state":"retired"`)
+ _, registered := reg.Fence(subject.FromSandboxUID("a"))
+ require.False(t, registered)
+}
+
+func TestActionsV2RetiresAnOwnerBeforeItsFirstSet(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ observation := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2OwnerPathPrefix+"a", owner, "")
+ require.Equal(t, http.StatusOK, observation.Code)
+ require.Contains(t, observation.Body.String(), `"state":"absent"`)
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationRemoveBinding, owner, nil)).Code)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())).Code)
+ _, registered := reg.Fence(subject.FromSandboxUID("a"))
+ require.False(t, registered)
+}
+
+func TestActionsV2RestoresSameOwnerButRejectsUnknownPersistentState(t *testing.T) {
+ srv, _, _ := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ set := actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, set).Code)
+ restarted, _, _ := fastSandboxTestServer(t)
+ restarted.SetPolicyFiles(srv.policyFiles)
+ restarted.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ require.Equal(t, http.StatusOK, doActionsV2(t, restarted, set).Code)
+ f, err := restarted.ownerFile(subject.FromSandboxUID("a"))
+ require.NoError(t, err)
+ _, err = f.SaveRaw([]byte(`{"version":"unknown"}`))
+ require.NoError(t, err)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, restarted, set).Code)
+ require.Equal(t, http.StatusPreconditionFailed, doActionsV2Relay(t, restarted, http.MethodPost, constants.ActionsV2VaultRelayPathPrefix+"a", owner, vaultCredential()).Code)
+}
+
+func TestActionsV2OwnerPersistenceAndRetirementFailuresRemainClosed(t *testing.T) {
+ srv, reg, nft := fastSandboxTestServer(t)
+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)
+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)
+ subj := subject.FromSandboxUID("a")
+ file, err := srv.ownerFile(subj)
+ require.NoError(t, err)
+ fault := file.(*fakeVaultFile)
+ fault.saveState, fault.saveErr = policy.FileUnknown, fmt.Errorf("injected uncertain owner persistence")
+ set := actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())
+ require.Equal(t, http.StatusServiceUnavailable, doActionsV2(t, srv, set).Code)
+ _, registered := reg.Fence(subj)
+ require.False(t, registered, "no SET effects before owner persistence")
+ fault.saveState, fault.saveErr = policy.FileCommitted, nil
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, set).Code)
+ nft.removeErr = fmt.Errorf("injected cleanup failure")
+ remove := actionsV2Body(t, actionhandler.OperationRemoveBinding, owner, nil)
+ require.NotEqual(t, http.StatusOK, doActionsV2(t, srv, remove).Code)
+ record, err := srv.readOwnerRecord(subj)
+ require.NoError(t, err)
+ require.Equal(t, "retiring", record.Phase)
+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, set).Code)
+ nft.removeErr = nil
+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, remove).Code)
+ record, err = srv.readOwnerRecord(subj)
+ require.NoError(t, err)
+ require.Equal(t, "retired", record.Phase)
+}
diff --git a/components/egress/fastsandbox_owner.go b/components/egress/fastsandbox_owner.go
new file mode 100644
index 000000000..73615a50d
--- /dev/null
+++ b/components/egress/fastsandbox_owner.go
@@ -0,0 +1,133 @@
+// 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 main
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/alibaba/opensandbox/egress/pkg/actionhandler"
+ "github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// Owner records outlive policy/Vault deletion. A retired UID is not reusable
+// in this first strict slice; callers create a new UID instead of rebinding.
+type strictOwnerRecord struct {
+ Version string `json:"version"`
+ Mode string `json:"mode"`
+ Owner actionhandler.Owner `json:"owner"`
+ Phase string `json:"phase"`
+}
+
+// Disabling the opt-in must not turn an existing strict domain into a v1
+// writer. Older binaries remain outside this deployment contract.
+func validateOwnerDomain(dir, version string) error {
+ if version == constants.ActionsAPIVersionV2 || strings.TrimSpace(dir) == "" {
+ return nil
+ }
+ entries, err := os.ReadDir(dir)
+ if os.IsNotExist(err) {
+ return nil
+ }
+ if err != nil {
+ return err
+ }
+ for _, entry := range entries {
+ if strings.HasSuffix(entry.Name(), ".json.owner") {
+ return fmt.Errorf("strict owner records exist; Actions v1 cannot open this domain")
+ }
+ }
+ return nil
+}
+
+func (s *fastSandboxPolicyServer) ownerFile(subj subject.Subject) (vaultFileStore, error) {
+ s.mu.Lock()
+ p := s.policyFiles
+ s.mu.Unlock()
+ if p == nil {
+ return nil, fmt.Errorf("strict owner persistence is unavailable")
+ }
+ // Use the same trusted directory and atomic writer, but never the policy
+ // filename: ordinary policy deletion must not erase the owner fence.
+ p.mu.Lock()
+ defer p.mu.Unlock()
+ path, err := p.pathFor(subj)
+ if err != nil {
+ return nil, err
+ }
+ return p.newFile(filepath.Clean(path) + ".owner")
+}
+
+// The caller holds the subject owner stripe across this read and its effects.
+func (s *fastSandboxPolicyServer) readOwnerRecord(subj subject.Subject) (*strictOwnerRecord, error) {
+ f, err := s.ownerFile(subj)
+ if err != nil {
+ return nil, err
+ }
+ snapshot, err := f.Snapshot()
+ if err != nil || !snapshot.Exists() {
+ return nil, err
+ }
+ var record strictOwnerRecord
+ decoder := json.NewDecoder(bytes.NewReader(snapshot.Data()))
+ decoder.DisallowUnknownFields()
+ if err := decoder.Decode(&record); err != nil {
+ return nil, fmt.Errorf("invalid strict owner record: %w", err)
+ }
+ if decoder.Decode(new(any)) != io.EOF || record.Version != constants.ActionsAPIVersionV2 ||
+ record.Mode != "legacy" || !record.Owner.Valid() || subject.FromSandboxUID(record.Owner.SandboxUID) != subj ||
+ (record.Phase != "active" && record.Phase != "retiring" && record.Phase != "retired") {
+ return nil, fmt.Errorf("unsupported or inconsistent strict owner record")
+ }
+ return &record, nil
+}
+
+func (s *fastSandboxPolicyServer) writeOwnerRecord(subj subject.Subject, owner actionhandler.Owner, phase string) error {
+ f, err := s.ownerFile(subj)
+ if err != nil {
+ return err
+ }
+ data, err := json.Marshal(strictOwnerRecord{Version: constants.ActionsAPIVersionV2, Mode: "legacy", Owner: owner, Phase: phase})
+ if err != nil {
+ return err
+ }
+ state, err := f.SaveRaw(data)
+ if err != nil || state != policy.FileCommitted {
+ return fmt.Errorf("strict owner persistence not confirmed (state %v): %v", state, err)
+ }
+ return nil
+}
+
+func (s *fastSandboxPolicyServer) cleanOwnerSubject(subj subject.Subject) error {
+ s.mu.Lock()
+ residual := s.subjectHasLiveStateLocked(subj)
+ s.mu.Unlock()
+ _, registered := s.reg.Fence(subj)
+ if residual || registered {
+ return fmt.Errorf("unclassified subject runtime state exists")
+ }
+ residual, err := s.subjectHasPersistentState(subj)
+ if err != nil || residual {
+ return fmt.Errorf("subject persistence is not confirmed empty")
+ }
+ return nil
+}
diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.go
index 4a345e168..22dbb4abf 100644
--- a/components/egress/pkg/actionhandler/actionhandler.go
+++ b/components/egress/pkg/actionhandler/actionhandler.go
@@ -204,6 +204,7 @@ func (b *Binding) InputString() (string, error) {
// Envelope is the full request body of POST /_fastlet/v1/actions.
type Envelope struct {
+ Mode string `json:"mode,omitempty"`
APIVersion string `json:"apiVersion"`
Operation Operation `json:"operation"`
InvocationID string `json:"invocationId"`
@@ -252,6 +253,9 @@ func (e *Envelope) ValidateVersion(version string) error {
return fmt.Errorf("sandbox.uid is required")
}
if version == APIVersionV2 {
+ if e.Mode != "legacy" {
+ return fmt.Errorf("Actions v2 requires explicit legacy mode; other modes are unsupported")
+ }
if e.Owner == nil || !e.Owner.Valid() || e.Owner.SandboxUID != e.Sandbox.UID ||
e.Owner.RuntimeInstanceID != e.Revision.RuntimeInstanceID || e.Owner.AttachmentID != e.Revision.AttachmentID ||
uint64(e.Owner.RouteGeneration) != e.Revision.RouteGeneration {
diff --git a/docs/architecture/network/egress.md b/docs/architecture/network/egress.md
index deae0ad12..9854e6290 100644
--- a/docs/architecture/network/egress.md
+++ b/docs/architecture/network/egress.md
@@ -59,6 +59,9 @@ Layers 1 and 2 decide *whether* a connection may happen; the transparent MITM la
The Fast Sandbox management transport has a separate `OPENSANDBOX_EGRESS_ACTIONS_API_VERSION` switch (default v1). Its experimental v2 value only selects strict Actions/relay HTTP routes; it does not enable the OSEP-0023 revision runtime or TLS interception. A v2 Fastlet Pool and every egress Handler must use the same version. V2 supports legacy-mode binding and Vault/Policy relay operations for clean-base Firecracker sandboxes; snapshots, template state, pause/resume, and restore are unsupported. Owner metadata fences the Sandbox runtime but is not caller authentication. Because the listener is on Pod-netns loopback, verify management-port isolation for the exact Fastlet Pod composition before enabling v2; this code does not configure or test that isolation.
+Strict requests carry an explicit `mode: legacy`. The egress persists the complete owner and `active`/`retiring`/`retired` phase in `<policy-dir>/<uid>.json.owner` using the existing atomic writer. Retirement records are retained without credential material; late SET/Hook/relay operations cannot revive them after restart. This slice rejects same-UID rebind and live `SET null`; use terminal Sandbox Delete and a new UID. A never-registered owner is reported as `absent`, not `retired`; REMOVE first writes its terminal fence. Reopening a directory containing owner records with the v1 switch is rejected. Do not delete these records or roll the whole deployment back to an older binary that does not understand them.
+
+
The internal sidecar experiment covers bound HTTPS/443 HTTP/1.1 traffic and experimental HTTP/2 admission and bounded-drain wiring on the fixed-dependency direct/lazy path. Configured chained upstream proxies remain rejected for live HTTP/2. Long-held responses can still cause Go retries to time out; full client migration and Linux acceptance remain follow-up work. Key properties:
- Admission is per connection and per request, from an immutable snapshot installed over an authenticated channel; unknown or mismatched state denies — the mode never falls back to decrypt-all.