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.goindex ad2aa6338..4f33caf48 100644--- a/components/egress/fastsandbox.go+++ b/components/egress/fastsandbox.go@@ -71,6 +71,9 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstreamif 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.goindex 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 *httphttp.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, ruid := 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 *hreturn 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.goindex 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 mainimport ("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) actiofunc 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 *testirequire.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.gonew file mode 100644index 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.goindex 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.mdindex 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 laThe 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.