Secure, Fast, and Extensible Sandbox runtime for AI agents.
feat(egress): add strict FastSandbox Actions v2 receiver
lihaopengba9d4167a7bc
diff --git a/components/egress/fastsandbox.go b/components/egress/fastsandbox.goindex 145aa5514..ad2aa6338 100644--- a/components/egress/fastsandbox.go+++ b/components/egress/fastsandbox.go@@ -67,6 +67,10 @@ import (// on the shared dnsproxy.func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.UpstreamProxySpec) {log.Infof("egress profile: fast-sandbox (multi-sandbox control plane)")+ actionsAPIVersion, err := constants.ParseFastSandboxActionsAPIVersion(os.Getenv(constants.EnvFastSandboxActionsAPIVersion))+ if err != nil {+ log.Fatalf("fast-sandbox Actions protocol: %v", err)+ }otelShutdown, err := telemetry.Init(ctx)if err != nil {@@ -115,6 +119,7 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstreamreg := subject.NewRegistry(alwaysDeny, alwaysAllow)fastSandboxSrv := newFastSandboxPolicyServer(ctx, reg, podNft)+ fastSandboxSrv.SetActionsAPIVersion(actionsAPIVersion)// Register the configured state-directory basenames BEFORE either// constructor runs: the volume-root restriction must recognize thediff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.goindex 8c1255374..0a3c48170 100644--- a/components/egress/fastsandbox_actions.go+++ b/components/egress/fastsandbox_actions.go@@ -53,11 +53,14 @@ package mainimport ("context""crypto/rand"+ "encoding/base64""encoding/hex"+ "encoding/json""fmt""io""net/http""os"+ "strings""time""github.com/alibaba/opensandbox/egress/pkg/actionhandler"@@ -93,6 +96,10 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *http.Error(w, "method not allowed", http.StatusMethodNotAllowed)return}+ writeJSON(w, http.StatusOK, s.actionStatusResponse())+}++func (s *fastSandboxPolicyServer) actionStatusResponse() actionhandler.StatusResponse {recovery := s.vaultRecoveryActive()policyRecovery := s.policyRecoveryActive()degraded := s.degradedVaultUIDs()@@ -128,6 +135,18 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *resp.MitmCaError = reason}}+ return resp+}++func (s *fastSandboxPolicyServer) handleActionsV2Status(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodGet {+ w.Header().Set("Allow", http.MethodGet)+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)+ return+ }+ resp := s.actionStatusResponse()+ resp.APIVersion = constants.ActionsAPIVersionV2+ resp.OwnerStatus = truewriteJSON(w, http.StatusOK, resp)}@@ -159,6 +178,215 @@ func (s *fastSandboxPolicyServer) handleActions(w http.ResponseWriter, r *http.RwriteJSON(w, http.StatusOK, struct{}{})}+func (s *fastSandboxPolicyServer) handleActionsV2(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodPost {+ w.Header().Set("Allow", http.MethodPost)+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)+ return+ }+ body, err := io.ReadAll(io.LimitReader(r.Body, maxPolicyBodyBytes))+ if err != nil {+ http.Error(w, fmt.Sprintf("failed to read action body: %v", err), http.StatusBadRequest)+ return+ }+ env, err := actionhandler.ParseEnvelopeV2(body)+ if err != nil {+ http.Error(w, fmt.Sprintf("invalid Actions v2 envelope: %v", err), http.StatusBadRequest)+ return+ }+ subj := subject.FromSandboxUID(env.Sandbox.UID)+ ownerLock := s.ownerLock(subj)+ ownerLock.Lock()+ defer ownerLock.Unlock()+ if err := s.validateActionsV2Owner(subj, env); err != nil {+ http.Error(w, err.Error(), http.StatusConflict)+ return+ }+ switch env.Operation {+ case actionhandler.OperationSetBinding, actionhandler.OperationLifecycleHook, actionhandler.OperationRemoveBinding:+ default:+ http.Error(w, "snapshot and state-transfer operations are not supported by Actions v2", http.StatusNotImplemented)+ 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+ }+ s.mu.Lock()+ switch env.Operation {+ case actionhandler.OperationSetBinding:+ s.actionOwners[subj] = *env.Owner+ case actionhandler.OperationRemoveBinding:+ if current, ok := s.actionOwners[subj]; ok && current.Matches(*env.Owner) {+ delete(s.actionOwners, subj)+ }+ }+ s.mu.Unlock()+ writeJSON(w, http.StatusOK, struct{}{})+}++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")+ }+ 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")+ }+ return nil+ }+ if current.Matches(*env.Owner) {+ return nil+ }+ return fmt.Errorf("Actions v2 owner mismatch")+}++func (s *fastSandboxPolicyServer) handleActionsV2Owner(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodGet {+ w.Header().Set("Allow", http.MethodGet)+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)+ return+ }+ 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)+ return+ }+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))+ ownerLock.RLock()+ defer ownerLock.RUnlock()+ release, err := s.acquireAction(r.Context())+ if err != nil {+ http.Error(w, "owner observation canceled", 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})+ return+ }+ }+ if registered || residual {+ http.Error(w, "owner status is unknown; residual subject state exists", http.StatusConflict)+ return+ }+ residual, err = s.subjectHasPersistentState(subj)+ if err != nil || residual {+ http.Error(w, "owner retirement cannot be confirmed", http.StatusServiceUnavailable)+ return+ }+ if ownerFound {+ s.mu.Lock()+ if currentOwner, ok := s.actionOwners[subj]; ok && currentOwner.Matches(owner) {+ delete(s.actionOwners, subj)+ }+ s.mu.Unlock()+ }+ writeJSON(w, http.StatusOK, actionhandler.OwnerObservation{State: "retired", Owner: owner})+}++func (s *fastSandboxPolicyServer) subjectHasLiveStateLocked(subj subject.Subject) bool {+ _, rebind := s.rebinds[subj]+ _, vault := s.vaults[subj]+ _, policy := s.policies[subj]+ _, pending := s.pendingPolicies[subj]+ _, attachment := s.subjAtt[subj]+ _, fence := s.subjFence[subj]+ return rebind || vault || policy || pending || attachment || fence+}++func (s *fastSandboxPolicyServer) subjectHasPersistentState(subj subject.Subject) (bool, error) {+ if s.vaultFiles != nil {+ fs, err := s.vaultFiles.storeFor(subj)+ if err != nil {+ return false, err+ }+ snapshot, err := fs.Snapshot()+ if err != nil {+ return false, err+ }+ if snapshot.Exists() || s.vaultFiles.isSealed(subj) {+ return true, nil+ }+ }+ if s.policyFiles != nil {+ fs, err := s.policyFiles.storeFor(subj)+ if err != nil {+ return false, err+ }+ snapshot, err := fs.Snapshot()+ if err != nil {+ return false, err+ }+ if snapshot.Exists() || s.policyFiles.isSealed(subj) {+ return true, nil+ }+ }+ return false, nil+}++func ownerFromRequest(r *http.Request) (actionhandler.Owner, error) {+ encoded := strings.TrimSpace(r.Header.Get(constants.EgressActionsOwnerHeader))+ if encoded == "" {+ return actionhandler.Owner{}, fmt.Errorf("owner header is required")+ }+ decoded, err := base64.RawURLEncoding.DecodeString(encoded)+ if err != nil {+ return actionhandler.Owner{}, err+ }+ var owner actionhandler.Owner+ if err := json.Unmarshal(decoded, &owner); err != nil {+ return owner, err+ }+ if !owner.Valid() || strings.TrimSpace(r.Header.Get(constants.EgressActionsSandboxUIDHeader)) != owner.SandboxUID {+ return owner, fmt.Errorf("owner header is incomplete or disagrees with Sandbox UID header")+ }+ return owner, nil+}++func (s *fastSandboxPolicyServer) validateRelayOwner(w http.ResponseWriter, r *http.Request, uid string) bool {+ if s.actionsAPIVersion != constants.ActionsAPIVersionV2 {+ return true+ }+ owner, err := ownerFromRequest(r)+ if err != nil || owner.SandboxUID != uid {+ http.Error(w, "relay owner must match the path Sandbox UID", http.StatusBadRequest)+ return false+ }+ subj := subject.FromSandboxUID(uid)+ s.mu.Lock()+ current, found := s.actionOwners[subj]+ s.mu.Unlock()+ if !found || !current.Matches(owner) {+ http.Error(w, "relay owner is not the current registered owner", http.StatusPreconditionFailed)+ return false+ }+ return true+}+// dispatchAction validates effect-free input before entering the cancellable// action gate. Every runtime registry writer is reached through this gate;// snapshot transfers retain their own Vault transaction/guard semantics.diff --git a/components/egress/fastsandbox_actions_v2_test.go b/components/egress/fastsandbox_actions_v2_test.gonew file mode 100644index 000000000..25b9a1a72--- /dev/null+++ b/components/egress/fastsandbox_actions_v2_test.go@@ -0,0 +1,200 @@+package main++import (+ "encoding/base64"+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "net/netip"+ "strings"+ "testing"++ "github.com/alibaba/opensandbox/egress/pkg/actionhandler"+ "github.com/alibaba/opensandbox/egress/pkg/constants"+ "github.com/alibaba/opensandbox/egress/pkg/subject"+ "github.com/stretchr/testify/require"+)++func actionsV2Owner(uid, runtimeID, attachmentID string, generation int64) actionhandler.Owner {+ return actionhandler.Owner{+ SandboxUID: uid, FastletPodUID: "fastlet-pod", RuntimeInstanceID: runtimeID,+ InstanceGeneration: generation, AssignmentAttempt: 1, RouteGeneration: 1, AttachmentID: attachmentID,+ }+}++func actionsV2Body(t *testing.T, operation actionhandler.Operation, owner actionhandler.Owner, input *string) string {+ t.Helper()+ env := actionhandler.Envelope{+ 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)},+ }+ if operation == actionhandler.OperationSetBinding {+ env.Attachment = testAttachment()+ if owner.SandboxUID == "b" {+ env.Attachment.Network.IP = netip.MustParseAddr("10.0.0.6")+ }+ if input == nil {+ null := []byte("null")+ env.Binding = &actionhandler.Binding{Input: null}+ } else {+ encoded, err := json.Marshal(*input)+ require.NoError(t, err)+ env.Binding = &actionhandler.Binding{Input: encoded}+ }+ }+ if operation == actionhandler.OperationLifecycleHook {+ env.Hook = &actionhandler.Hook{Name: actionhandler.HookDataPlaneReady, Sequence: 2}+ }+ encoded, err := json.Marshal(env)+ require.NoError(t, err)+ return string(encoded)+}++func doActionsV2(t *testing.T, srv *fastSandboxPolicyServer, body string) *httptest.ResponseRecorder {+ t.Helper()+ return doRequest(t, srv, http.MethodPost, constants.ActionsV2DispatchPath, body)+}++func doActionsV2Relay(t *testing.T, srv *fastSandboxPolicyServer, method, path string, owner actionhandler.Owner, body string) *httptest.ResponseRecorder {+ t.Helper()+ req := httptest.NewRequest(method, path, strings.NewReader(body))+ encoded, err := json.Marshal(owner)+ require.NoError(t, err)+ req.Header.Set(constants.EgressActionsOwnerHeader, base64.RawURLEncoding.EncodeToString(encoded))+ req.Header.Set(constants.EgressActionsSandboxUIDHeader, owner.SandboxUID)+ rec := httptest.NewRecorder()+ srv.Handler().ServeHTTP(rec, req)+ return rec+}++func TestActionsV2IsOptInAndDoesNotMountLegacyMutationRoutes(t *testing.T) {+ srv, _, _ := fastSandboxTestServer(t)+ legacy := srv.Handler()+ for _, path := range []string{constants.ActionsV2StatusPath, constants.ActionsV2DispatchPath, constants.ActionsV2VaultRelayPathPrefix + "a"} {+ rec := httptest.NewRecorder()+ legacy.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))+ require.Equal(t, http.StatusNotFound, rec.Code, path)+ }++ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)+ strict := srv.Handler()+ for _, path := range []string{constants.ActionsStatusPath, constants.ActionsDispatchPath, constants.VaultRelayPathPrefix + "a"} {+ rec := httptest.NewRecorder()+ strict.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))+ require.Equal(t, http.StatusNotFound, rec.Code, path)+ }+ status := httptest.NewRecorder()+ strict.ServeHTTP(status, httptest.NewRequest(http.MethodGet, constants.ActionsV2StatusPath, nil))+ require.Equal(t, http.StatusOK, status.Code)+ var response actionhandler.StatusResponse+ require.NoError(t, json.Unmarshal(status.Body.Bytes(), &response))+ require.Equal(t, actionhandler.APIVersionV2, response.APIVersion)+ require.True(t, response.OwnerStatus)+}++func TestActionsV2SeparatesSubjectsAndFencesOwnerChanges(t *testing.T) {+ srv, reg, nft := fastSandboxTestServer(t)+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)+ policyInput := vaultAllowPolicy()+ a := actionsV2Owner("a", "runtime-a", "attachment-a", 1)+ b := actionsV2Owner("b", "runtime-b", "attachment-b", 1)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, a, policyInput)).Code)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, b, policyInput)).Code)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationLifecycleHook, a, nil)).Code)++ subjA, subjB := subject.FromSandboxUID("a"), subject.FromSandboxUID("b")+ beforeDeny, beforePolicy := len(nft.denyFirst), len(nft.policyApplied)+ newOwnerA := actionsV2Owner("a", "runtime-a2", "attachment-a2", 2)+ require.Equal(t, http.StatusConflict, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, newOwnerA, policyInput)).Code,+ "a replacement owner must first retire the old exact owner")+ require.Len(t, nft.denyFirst, beforeDeny)+ require.Len(t, nft.policyApplied, beforePolicy)++ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationRemoveBinding, a, nil)).Code)+ _, foundA := reg.Fence(subjA)+ _, foundB := reg.Fence(subjB)+ require.False(t, foundA)+ require.True(t, foundB, "retiring subject A must not affect B")+ srv.mu.Lock()+ gotB, foundB := srv.actionOwners[subjB]+ srv.mu.Unlock()+ require.True(t, foundB)+ require.True(t, gotB.Matches(b))++ newOwnerABody := actionsV2Body(t, actionhandler.OperationSetBinding, newOwnerA, policyInput)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, newOwnerABody).Code)+}++func TestActionsV2RejectsSnapshotAndRelayPathOwnerMismatchBeforeEffects(t *testing.T) {+ srv, reg, nft := fastSandboxTestServer(t)+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)+ owner := actionsV2Owner("a", "runtime-a", "attachment-a", 1)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, owner, vaultAllowPolicy())).Code)+ fenceBefore, registeredBefore := reg.Fence(subject.FromSandboxUID("a"))+ require.True(t, registeredBefore)+ beforeDeny := len(nft.denyFirst)+ snapshot, err := json.Marshal(actionhandler.Envelope{+ 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"},+ })+ require.NoError(t, err)+ require.Equal(t, http.StatusNotImplemented, doActionsV2(t, srv, string(snapshot)).Code)+ fenceAfter, registered := reg.Fence(subject.FromSandboxUID("a"))+ require.True(t, registered)+ require.True(t, fenceBefore.Matches(fenceAfter))+ require.Len(t, nft.denyFirst, beforeDeny)++ other := actionsV2Owner("b", "runtime-b", "attachment-b", 1)+ rec := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2VaultRelayPathPrefix+"b", owner, "")+ require.Equal(t, http.StatusBadRequest, rec.Code)+ _, registered = reg.Fence(subject.FromSandboxUID("b"))+ require.False(t, registered)+ require.NotEqual(t, owner.SandboxUID, other.SandboxUID)+}++func TestActionsV2CarriesOwnerThroughVaultAndPolicyRelayCRUD(t *testing.T) {+ srv, reg, _ := fastSandboxTestServer(t)+ srv.SetActionsAPIVersion(actionhandler.APIVersionV2)+ input := vaultAllowPolicy()+ ownerA := actionsV2Owner("a", "runtime-a", "attachment-a", 1)+ ownerB := actionsV2Owner("b", "runtime-b", "attachment-b", 1)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationSetBinding, ownerA, input)).Code)+ require.Equal(t, http.StatusOK, doActionsV2(t, srv, actionsV2Body(t, actionhandler.OperationLifecycleHook, ownerA, nil)).Code)++ created := doActionsV2Relay(t, srv, http.MethodPost, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, vaultCredential())+ require.Equal(t, http.StatusCreated, created.Code, created.Body.String())+ readVault := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, "")+ require.Equal(t, http.StatusOK, readVault.Code, readVault.Body.String())+ require.Contains(t, readVault.Body.String(), `"name":"tok"`)++ readPolicy := doActionsV2Relay(t, srv, http.MethodGet, constants.ActionsV2PolicyRelayPathPrefix+"a", ownerA, "")+ require.Equal(t, http.StatusOK, readPolicy.Code, readPolicy.Body.String())+ revision, current := mustPolicyRevision(t, readPolicy)+ require.EqualValues(t, 1, revision)+ updated := doActionsV2Relay(t, srv, http.MethodPut, constants.ActionsV2PolicyRelayPathPrefix+"a", ownerA,+ policyPutDoc(policyAllowAlt(), revision, true, false))+ require.Equal(t, http.StatusOK, updated.Code, updated.Body.String())+ require.Contains(t, updated.Body.String(), "other.example.com")+ _ = current++ deleted := doActionsV2Relay(t, srv, http.MethodDelete, constants.ActionsV2VaultRelayPathPrefix+"a", ownerA, "")+ require.Equal(t, http.StatusNoContent, deleted.Code, deleted.Body.String())++ // A different, unbound Sandbox cannot use A's shared management routes.+ for _, request := range []struct {+ method string+ path string+ body string+ }{+ {http.MethodGet, constants.ActionsV2VaultRelayPathPrefix + "b", ""},+ {http.MethodPost, constants.ActionsV2VaultRelayPathPrefix + "b", vaultCredential()},+ {http.MethodGet, constants.ActionsV2PolicyRelayPathPrefix + "b", ""},+ } {+ rec := doActionsV2Relay(t, srv, request.method, request.path, ownerB, request.body)+ require.Equal(t, http.StatusPreconditionFailed, rec.Code, rec.Body.String())+ }+ _, found := reg.Fence(subject.FromSandboxUID("b"))+ require.False(t, found, "relay must not materialize an unbound subject")+}diff --git a/components/egress/fastsandbox_policy.go b/components/egress/fastsandbox_policy.goindex 7a3c0f9fd..9ad078b8c 100644--- a/components/egress/fastsandbox_policy.go+++ b/components/egress/fastsandbox_policy.go@@ -66,11 +66,23 @@ const maxPolicyRelayBodyBytes = policy.MaxPolicyBodyBytes + 1<<10// handlePolicyRelay serves /policy/{sandboxUid} for all relay verbs.func (s *fastSandboxPolicyServer) handlePolicyRelay(w http.ResponseWriter, r *http.Request) {- uid := strings.TrimPrefix(r.URL.Path, constants.PolicyRelayPathPrefix)+ prefix := constants.PolicyRelayPathPrefix+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {+ prefix = constants.ActionsV2PolicyRelayPathPrefix+ }+ uid := strings.TrimPrefix(r.URL.Path, prefix)if !validVaultSubjectID(uid) {http.Error(w, "missing or invalid sandbox uid in path", http.StatusBadRequest)return}+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))+ ownerLock.RLock()+ defer ownerLock.RUnlock()+ }+ if !s.validateRelayOwner(w, r, uid) {+ return+ }subj := subject.FromSandboxUID(uid)switch r.Method {case http.MethodGet:diff --git a/components/egress/fastsandbox_server.go b/components/egress/fastsandbox_server.goindex 6256a84c7..f2e892f9a 100644--- a/components/egress/fastsandbox_server.go+++ b/components/egress/fastsandbox_server.go@@ -25,6 +25,7 @@ package mainimport ("context""fmt"+ "hash/crc32""net/http""net/netip""strings"@@ -135,27 +136,46 @@ type fastSandboxPolicyServer struct {// makes the Fastlet invalidate Binding readiness and replay SET_BINDING// followed by the reached Hooks (restart recovery).instanceID string+ // actionsAPIVersion is one protocol for the whole shared Fastlet domain.+ // V2 is explicit and default-off; in that mode v1 action and relay routes+ // are not mounted, so older senders fail closed.+ actionsAPIVersion string+ actionOwners map[subject.Subject]actionhandler.Owner+ actionOwnerLocks [256]sync.RWMutex}func newFastSandboxPolicyServer(ctx context.Context, reg *subject.MemoryRegistry, nft fastSandboxNftApplier) *fastSandboxPolicyServer {return &fastSandboxPolicyServer{- ctx: ctx,- reg: reg,- nft: nft,- actionGate: make(chan struct{}, 1),- rebinds: make(map[subject.Subject]*subjectRebind),- vaults: make(map[subject.Subject]vaultEntry),- pendingPolicies: make(map[subject.Subject]*policy.NetworkPolicy),- policies: make(map[subject.Subject]*policyEntry),- subjAtt: make(map[subject.Subject]actionhandler.NetworkAttachment),- subjFence: make(map[subject.Subject]subject.Fencing),- gatewayDNSRefs: make(map[subject.Subject]netip.Addr),- dnsRedirectApply: iptables.ReplaceGatewayDNSRedirects,- mitmEntries: make(map[subject.Subject]iptables.MitmRedirectEntry),- instanceID: newHandlerInstanceID(),+ ctx: ctx,+ reg: reg,+ nft: nft,+ actionGate: make(chan struct{}, 1),+ rebinds: make(map[subject.Subject]*subjectRebind),+ vaults: make(map[subject.Subject]vaultEntry),+ pendingPolicies: make(map[subject.Subject]*policy.NetworkPolicy),+ policies: make(map[subject.Subject]*policyEntry),+ subjAtt: make(map[subject.Subject]actionhandler.NetworkAttachment),+ subjFence: make(map[subject.Subject]subject.Fencing),+ gatewayDNSRefs: make(map[subject.Subject]netip.Addr),+ dnsRedirectApply: iptables.ReplaceGatewayDNSRedirects,+ mitmEntries: make(map[subject.Subject]iptables.MitmRedirectEntry),+ instanceID: newHandlerInstanceID(),+ actionsAPIVersion: constants.ActionsAPIVersion,+ actionOwners: make(map[subject.Subject]actionhandler.Owner),}}+func (s *fastSandboxPolicyServer) SetActionsAPIVersion(version string) {+ s.actionsAPIVersion = version+}++func (s *fastSandboxPolicyServer) ownerLock(subj subject.Subject) *sync.RWMutex {+ // Subject names are caller-provided identifiers. A bounded stripe set+ // prevents requests for arbitrary subjects from growing a lock map forever;+ // hash collisions only serialize otherwise independent subjects.+ return &s.actionOwnerLocks[crc32.ChecksumIEEE([]byte(subj))%uint32(len(s.actionOwnerLocks))]+}+// SetMitm wires the shared mitmproxy into the control plane: the healthz gate// and the per-subject interception redirect install/remove. Called once at// assembly, before the controller starts; a nil gate (MITM disabled) leaves@@ -259,10 +279,18 @@ func cloneGatewayDNSRefs(refs map[subject.Subject]netip.Addr) map[subject.Subjec// the healthz probe. No proxy-route surface.func (s *fastSandboxPolicyServer) Handler() http.Handler {mux := http.NewServeMux()- mux.HandleFunc(constants.ActionsStatusPath, s.handleActionsStatus)- mux.HandleFunc(constants.ActionsDispatchPath, s.handleActions)- mux.HandleFunc(constants.VaultRelayPathPrefix, s.handleVaultRelay)- mux.HandleFunc(constants.PolicyRelayPathPrefix, s.handlePolicyRelay)+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {+ mux.HandleFunc(constants.ActionsV2StatusPath, s.handleActionsV2Status)+ mux.HandleFunc(constants.ActionsV2DispatchPath, s.handleActionsV2)+ mux.HandleFunc(constants.ActionsV2OwnerPathPrefix, s.handleActionsV2Owner)+ mux.HandleFunc(constants.ActionsV2VaultRelayPathPrefix, s.handleVaultRelay)+ mux.HandleFunc(constants.ActionsV2PolicyRelayPathPrefix, s.handlePolicyRelay)+ } else {+ mux.HandleFunc(constants.ActionsStatusPath, s.handleActionsStatus)+ mux.HandleFunc(constants.ActionsDispatchPath, s.handleActions)+ mux.HandleFunc(constants.VaultRelayPathPrefix, s.handleVaultRelay)+ mux.HandleFunc(constants.PolicyRelayPathPrefix, s.handlePolicyRelay)+ }mux.HandleFunc("/healthz", s.handleHealthz)return mux}diff --git a/components/egress/fastsandbox_vault.go b/components/egress/fastsandbox_vault.goindex 6a3c4dbf4..50adf95dc 100644--- a/components/egress/fastsandbox_vault.go+++ b/components/egress/fastsandbox_vault.go@@ -59,11 +59,23 @@ func validVaultSubjectID(uid string) bool {// handleVaultRelay serves /vault/{sandboxUid} for all four relay verbs.func (s *fastSandboxPolicyServer) handleVaultRelay(w http.ResponseWriter, r *http.Request) {- uid := strings.TrimPrefix(r.URL.Path, constants.VaultRelayPathPrefix)+ prefix := constants.VaultRelayPathPrefix+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {+ prefix = constants.ActionsV2VaultRelayPathPrefix+ }+ uid := strings.TrimPrefix(r.URL.Path, prefix)if !validVaultSubjectID(uid) {http.Error(w, "missing or invalid sandbox uid in path", http.StatusBadRequest)return}+ if s.actionsAPIVersion == constants.ActionsAPIVersionV2 {+ ownerLock := s.ownerLock(subject.FromSandboxUID(uid))+ ownerLock.RLock()+ defer ownerLock.RUnlock()+ }+ if !s.validateRelayOwner(w, r, uid) {+ return+ }subj := subject.FromSandboxUID(uid)switch r.Method {case http.MethodGet:diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.goindex 257cf2e6f..4a345e168 100644--- a/components/egress/pkg/actionhandler/actionhandler.go+++ b/components/egress/pkg/actionhandler/actionhandler.go@@ -43,6 +43,7 @@ import (// APIVersion is the only accepted protocol version.const APIVersion = "sandbox.fast.io/actions/v1"+const APIVersionV2 = "sandbox.fast.io/actions/v2"// Operation is the action operation code.type Operation string@@ -91,6 +92,31 @@ type Revision struct {RouteGeneration uint64 `json:"routeGeneration"`}+// Owner is the complete platform-validated runtime fence carried by Actions+// v2. It prevents delayed operations from being reinterpreted for a new slot+// occupant; it is not caller authentication.+type Owner struct {+ SandboxUID string `json:"sandboxUid"`+ FastletPodUID string `json:"fastletPodUid"`+ RuntimeInstanceID string `json:"runtimeInstanceId"`+ InstanceGeneration int64 `json:"instanceGeneration"`+ AssignmentAttempt int64 `json:"assignmentAttempt"`+ RouteGeneration int64 `json:"routeGeneration"`+ AttachmentID string `json:"attachmentId"`+}++func (o Owner) Valid() bool {+ return o.SandboxUID != "" && o.FastletPodUID != "" && o.RuntimeInstanceID != "" &&+ o.InstanceGeneration > 0 && o.AssignmentAttempt > 0 && o.RouteGeneration > 0 && o.AttachmentID != ""+}++func (o Owner) Matches(other Owner) bool { return o == other }++type OwnerObservation struct {+ State string `json:"state"`+ Owner Owner `json:"owner"`+}+// NetworkAttachment is the network identity material the egress consumes:// the dispatch key (SourceIP), the DNS/MITM targets (Gateway), the UDP// spoofing defense (HostVeth iifname), and sibling isolation (PrivateCIDR).@@ -183,6 +209,7 @@ type Envelope struct {InvocationID string `json:"invocationId"`Sandbox SandboxRef `json:"sandbox"`Revision Revision `json:"revision"`+ Owner *Owner `json:"owner,omitempty"`Attachment *Attachment `json:"attachment,omitempty"`Hook *Hook `json:"hook,omitempty"`Binding *Binding `json:"binding,omitempty"`@@ -193,11 +220,19 @@ type Envelope struct {// the message is not a well-formed, understood action; the caller must fail// closed (HTTP 400).func ParseEnvelope(body []byte) (*Envelope, error) {+ return ParseEnvelopeVersion(body, APIVersion)+}++func ParseEnvelopeV2(body []byte) (*Envelope, error) {+ return ParseEnvelopeVersion(body, APIVersionV2)+}++func ParseEnvelopeVersion(body []byte, version string) (*Envelope, error) {var e Envelopeif err := json.Unmarshal(body, &e); err != nil {return nil, fmt.Errorf("invalid action envelope: %w", err)}- if err := e.Validate(); err != nil {+ if err := e.ValidateVersion(version); err != nil {return nil, err}return &e, nil@@ -206,12 +241,25 @@ func ParseEnvelope(body []byte) (*Envelope, error) {// Validate checks the protocol-level invariants. Field-level semantics (fence// matching, registration state) are the caller's responsibility.func (e *Envelope) Validate() error {- if e.APIVersion != APIVersion {- return fmt.Errorf("unsupported apiVersion %q (want %q)", e.APIVersion, APIVersion)+ return e.ValidateVersion(APIVersion)+}++func (e *Envelope) ValidateVersion(version string) error {+ if e.APIVersion != version {+ return fmt.Errorf("unsupported apiVersion %q (want %q)", e.APIVersion, version)}if e.Sandbox.UID == "" {return fmt.Errorf("sandbox.uid is required")}+ if version == APIVersionV2 {+ 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 {+ return fmt.Errorf("Actions v2 requires an owner matching the sandbox and revision")+ }+ } else if e.Owner != nil {+ return fmt.Errorf("Actions v1 must not carry an Actions v2 owner")+ }switch e.Operation {case OperationSetBinding:if e.Binding == nil {@@ -286,9 +334,10 @@ func (e *Envelope) Fencing() (runtimeInstanceID, attachmentID string) {// The MitmCa* fields are additive observability (OSEP-0022 pinned CA):// consumers unaware of them ignore the extra JSON keys.type StatusResponse struct {- APIVersion string `json:"apiVersion"`- Ready bool `json:"ready"`- InstanceID string `json:"instanceId"`+ APIVersion string `json:"apiVersion"`+ Ready bool `json:"ready"`+ InstanceID string `json:"instanceId"`+ OwnerStatus bool `json:"ownerStatus,omitempty"`// MitmCaFingerprint is the pinned MITM CA's SHA-256 fingerprint// (lowercase hex over the DER); empty when MITM is disabled or no CA is// provisioned.diff --git a/components/egress/pkg/constants/configuration.go b/components/egress/pkg/constants/configuration.goindex 3dc479a3a..2ce9d3f5d 100644--- a/components/egress/pkg/constants/configuration.go+++ b/components/egress/pkg/constants/configuration.go@@ -15,11 +15,25 @@package constantsimport (+ "fmt""os""strconv""strings")+func ParseFastSandboxActionsAPIVersion(raw string) (string, error) {+ version := strings.TrimSpace(raw)+ if version == "" {+ return ActionsAPIVersion, nil+ }+ switch version {+ case ActionsAPIVersion, ActionsAPIVersionV2:+ return version, nil+ default:+ return "", fmt.Errorf("unsupported Fast Sandbox Actions apiVersion %q", version)+ }+}+const (EnvCredentialVaultTrustedProxyCIDRs = "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS"EnvCredentialVaultRequireScopedMatch = "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_SCOPED_MATCH"@@ -43,9 +57,19 @@ const (// Lifecycle Hooks to the egress Handler over two Pod-loopback HTTP endpoints// on the action target port.const (- ActionsAPIVersion = "sandbox.fast.io/actions/v1"- ActionsStatusPath = "/_fastlet/v1/actions/status"- ActionsDispatchPath = "/_fastlet/v1/actions"+ ActionsAPIVersion = "sandbox.fast.io/actions/v1"+ ActionsAPIVersionV2 = "sandbox.fast.io/actions/v2"+ ActionsStatusPath = "/_fastlet/v1/actions/status"+ ActionsDispatchPath = "/_fastlet/v1/actions"+ ActionsV2StatusPath = "/_fastlet/v2/actions/status"+ ActionsV2DispatchPath = "/_fastlet/v2/actions"+ ActionsV2OwnerPathPrefix = "/_fastlet/v2/owners/"+ ActionsV2RelayPathPrefix = "/_fastlet/v2/relay/"+ ActionsV2VaultRelayPathPrefix = ActionsV2RelayPathPrefix + "vault/"+ ActionsV2PolicyRelayPathPrefix = ActionsV2RelayPathPrefix + "policy/"+ EnvFastSandboxActionsAPIVersion = "OPENSANDBOX_EGRESS_ACTIONS_API_VERSION"+ EgressActionsOwnerHeader = "X-Fast-Sandbox-Owner"+ EgressActionsSandboxUIDHeader = "X-Sandbox-Uid"HookRuntimeReady = "sandbox.runtime-ready"HookDataPlaneReady = "sandbox.data-plane-ready"diff --git a/docs/architecture/network/egress.md b/docs/architecture/network/egress.mdindex cf42da97a..deae0ad12 100644--- a/docs/architecture/network/egress.md+++ b/docs/architecture/network/egress.md@@ -57,6 +57,8 @@ Layers 1 and 2 decide *whether* a connection may happen; the transparent MITM la::: warning Internal OSEP-0023 revision runtime`OPENSANDBOX_EGRESS_EXPERIMENTAL_REVISION_RUNTIME=true` is a development-only sidecar gate (default off) for the OSEP-0023 revision protocol. It adds no public configuration surface or supported `interceptionMode`, and does not enable Fast Sandbox.+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.+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.