Skip to content

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

feat(egress): egress-held policy relay surface and snapshot transfer

高然c1f66391ba32
diff --git a/components/egress/fastsandbox.go b/components/egress/fastsandbox.go
index d54bd477d..8fdfd6337 100644
--- a/components/egress/fastsandbox.go
+++ b/components/egress/fastsandbox.go
@@ -18,11 +18,15 @@
//
// Control flow:
//
-// fastlet action protocol --(SET_BINDING / LIFECYCLE_HOOK / REMOVE_BINDING)-->
+// fastlet action protocol --(SET_BINDING / LIFECYCLE_HOOK / REMOVE_BINDING /
+// VAULT_EXPORT / VAULT_IMPORT /
+// POLICY_EXPORT / POLICY_IMPORT)-->
// fastSandboxPolicyServer:18080 (loopback): subject lifecycle + deny-first nft,
-// policy activation on sandbox.data-plane-ready (the binding input is the
-// policy; the credential vault is egress-held behind the FastPath
-// handler-relay, OSEP-0022)
+// policy activation on sandbox.data-plane-ready. The binding input seeds the
+// policy at create; runtime mutations go through the handler-relay surfaces
+// (/policy/{uid} for the recorded policy, /vault/{uid} for the credential
+// vault, both egress-held per OSEP-0022) and the persisted files supersede
+// replayed binding inputs after a restart.
// DNS: one shared proxy, per-query policy via source IP dispatch
//
// Subject lifecycle is driven entirely by the Fastlet (Sandbox Actions
@@ -125,6 +129,23 @@ func runFastSandboxProfile(ctx context.Context, upstreamSpec *mitmproxy.Upstream
log.Infof("fast-sandbox vault persistence enabled at %s (one file per subject, atomic commit protocol)", vaultDir)
}
+ // Policy persistence: per-subject policy files under
+ // OPENSANDBOX_EGRESS_POLICY_DIR so an egress restart recovers the
+ // recorded policy locally at SET_BINDING replay (the committed file
+ // supersedes the replayed binding input) and the POLICY_EXPORT /
+ // POLICY_IMPORT snapshot transfer can carry it across pause/resume.
+ // Empty/unset keeps the policy memory-only. Fail fast on an unusable
+ // directory: silently serving memory-only would break the acked ⇒
+ // durable contract.
+ if policyDir := strings.TrimSpace(os.Getenv(constants.EnvEgressPolicyDir)); policyDir != "" {
+ pp, err := newPolicyPersistence(policyDir)
+ if err != nil {
+ log.Fatalf("fast-sandbox policy persistence: %v", err)
+ }
+ fastSandboxSrv.SetPolicyFiles(pp)
+ log.Infof("fast-sandbox policy persistence enabled at %s (one file per subject, atomic commit protocol)", policyDir)
+ }
+
// Shared mitmproxy (OSEP-0022 A1): one mitmdump in the Pod netns serving
// every sandbox. Started BEFORE the HTTP listener so subjects can never
// register against a missing interceptor (fail-closed registration); the
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.go
index a14ed50ee..2f6524973 100644
--- a/components/egress/fastsandbox_actions.go
+++ b/components/egress/fastsandbox_actions.go
@@ -38,6 +38,10 @@
// the subject — pause flow, before teardown.
// VAULT_IMPORT land the bundle re-stamped with the restored fence —
// resume flow, before data-plane-ready.
+// POLICY_EXPORT copy the recorded policy file into the snapshot bundle
+// and seal the subject — pause flow, before teardown.
+// POLICY_IMPORT land the policy bundle re-stamped with the restored
+// fence — resume flow, before data-plane-ready.
//
// Fail-closed invariants: the subject is deny-first from registration until
// its data-plane-ready Hook succeeds, so policy delivery can be late but
@@ -88,24 +92,30 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *
return
}
recovery := s.vaultRecoveryActive()
+ policyRecovery := s.policyRecoveryActive()
degraded := s.degradedVaultUIDs()
ready := true
if s.mitmGate != nil && s.mitmGate.MitmPending() {
ready = false
}
- if recovery {
+ if recovery || policyRecovery {
ready = false
}
resp := actionhandler.StatusResponse{
- APIVersion: constants.ActionsAPIVersion,
- Ready: ready,
- InstanceID: s.instanceID,
- Recovery: recovery,
- DegradedVaults: degraded,
+ APIVersion: constants.ActionsAPIVersion,
+ Ready: ready,
+ InstanceID: s.instanceID,
+ Recovery: recovery,
// Capability signal for the Fastlet's vault transfer: without vault
// persistence there is no vault state to hand off, so the transfer
// degrades (skips) rather than failing the checkpoint.
VaultTransfer: s.vaultFiles != nil,
+ // Capability signal for the Fastlet's policy transfer: without policy
+ // persistence there is no recorded policy to hand off, so the
+ // transfer degrades (skips) rather than failing the checkpoint.
+ PolicyTransfer: s.policyFiles != nil,
+ PolicyRecovery: s.policyRecoveryActive(),
+ DegradedVaults: degraded,
}
if s.mitmGate != nil {
resp.MitmCaFingerprint = s.mitmGate.CAFingerprint()
@@ -158,6 +168,10 @@ func (s *fastSandboxPolicyServer) dispatchAction(env *actionhandler.Envelope) (i
return s.applyVaultExport(env)
case actionhandler.OperationVaultImport:
return s.applyVaultImport(env)
+ case actionhandler.OperationPolicyExport:
+ return s.applyPolicyExport(env)
+ case actionhandler.OperationPolicyImport:
+ return s.applyPolicyImport(env)
default:
// Unreachable: ParseEnvelope validated the operation.
return http.StatusBadRequest, fmt.Errorf("unknown operation %q", env.Operation)
@@ -184,24 +198,29 @@ func (s *fastSandboxPolicyServer) applySetBinding(env *actionhandler.Envelope) (
}
// A fence change is a rebind: discard ALL prior per-subject state. The
// registry drops its entry inside RegisterAndEnforce; the vault slice
- // must go too (memory + persisted file), or the old instance's
- // credentials would survive into the successor's flows. Same-UID actions
- // serialize per subject; the vault relay writes hold the same lock for
- // their whole commit protocol.
+ // and the recorded policy must go too (memory + persisted files), or the
+ // old instance's credentials and policy would survive into the
+ // successor's flows. Same-UID actions serialize per subject; the vault
+ // and policy relay writes serialize against the same state.
if old, ok := s.reg.Fence(subj); ok && !old.Matches(fence) {
s.mu.Lock()
s.dropVault(subj)
+ delete(s.policies, subj)
+ s.purgePolicyFile(subj)
s.mu.Unlock()
- log.Infof("subject %s: rebind (%s -> %s), vault slice purged", subj, old.RuntimeInstanceID, fence.RuntimeInstanceID)
+ log.Infof("subject %s: rebind (%s -> %s), vault slice and policy record purged", subj, old.RuntimeInstanceID, fence.RuntimeInstanceID)
}
// Egress-restart recovery (OSEP-0022 stage 2): a subject with no live
// vault slice reloads its persisted file here, fenced by the full runtime
- // identity. This runs BEFORE the deny-first install so no interception
- // entry can materialize an empty slice ahead of the reload. A removal
- // binding skips the reload: with no policy to revalidate against, the
- // file stays fenced on disk until the next registration or terminal purge.
+ // identity. The recorded policy reloads the same way — the committed file
+ // is authoritative over the replayed binding input. These run BEFORE the
+ // deny-first install so no interception entry can materialize an empty
+ // slice ahead of the reload. A removal binding skips the reloads: with no
+ // policy to revalidate against, the files stay fenced on disk until the
+ // next registration or terminal purge.
if !env.Binding.IsRemoval() {
s.rehydrateVaultReload(subj, fence, pol)
+ s.rehydratePolicyReload(subj, fence)
}
state, err := s.reg.RegisterAndEnforce(subj, subject.SubjectKey{SourceIP: att.IP}, fence, func() error {
return s.OnRegistered(subj, att)
@@ -213,8 +232,10 @@ func (s *fastSandboxPolicyServer) applySetBinding(env *actionhandler.Envelope) (
if env.Binding.IsRemoval() {
// Binding removed from a still-live sandbox: drop the pending policy
// (a re-added binding gets a fresh input — never apply the removed
- // binding's policy to a policy-less subject).
+ // binding's policy to a policy-less subject) and purge the recorded
+ // policy, so deny-first is also the durable state.
s.clearPendingPolicy(subj)
+ s.clearPolicyRecord(subj)
if state == subject.StateActive {
if err := s.revertToDenyFirst(subj, att); err != nil {
return http.StatusInternalServerError, err
@@ -223,15 +244,11 @@ func (s *fastSandboxPolicyServer) applySetBinding(env *actionhandler.Envelope) (
log.Infof("subject %s: binding removed (deny-first)", subj)
return http.StatusOK, nil
}
- if state == subject.StateActive {
- // Ordinary input update on an already-ready sandbox: apply in place,
- // no Hook replay (the Fastlet does not send one for updates).
- if err := s.applyPolicy(subj, pol); err != nil {
- return http.StatusInternalServerError, fmt.Errorf("policy apply: %w", err)
- }
- } else {
- // Deny-first until sandbox.data-plane-ready activates the subject.
- s.storePendingPolicy(subj, pol)
+ // Install the binding policy (or honor the file-backed record that
+ // supersedes it) through the policy commit protocol.
+ if err := s.applyBindingPolicy(subj, fence, pol, state == subject.StateActive); err != nil {
+ log.Errorf("subject %s: binding policy commit failed: %v", subj, err)
+ return http.StatusInternalServerError, fmt.Errorf("binding policy commit: %w", err)
}
log.Infof("subject %s: SET_BINDING applied (state=%s)", subj, state)
return http.StatusOK, nil
diff --git a/components/egress/fastsandbox_policy.go b/components/egress/fastsandbox_policy.go
new file mode 100644
index 000000000..2de0abe4e
--- /dev/null
+++ b/components/egress/fastsandbox_policy.go
@@ -0,0 +1,410 @@
+// 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.
+
+// Relay policy surface: /policy/{sandboxUid} terminates the FastPath
+// handler-relay (server → FastPath → Fastlet → this loopback listener) for
+// the subject's recorded egress policy — the runtime twin of the vault relay
+// (fastsandbox_vault.go). The binding input seeds the policy at create; the
+// relay owns every runtime mutation, and the mutation is authoritative over
+// later binding replays (see rehydratePolicyReload).
+//
+// Surface: GET the recorded policy with its revision, PUT a full replace
+// with an optional expectedRevision (412 on mismatch, creates when absent),
+// DELETE reverting the subject to deny-first. POST/PATCH are deliberately
+// absent: creation is unconditional PUT, and a patch composes server-side
+// (relay GET → merge → relay PUT), mirroring the vault relay.
+//
+// Sidecar-parity guards on every op: unregistered subject → 404, never
+// cached; expectedIncarnation mismatch → 412; sealed (exported for a
+// pause checkpoint) → 409; policy persistence recovery latch → 503.
+// Validation failure → 400 NACK keeping last-good. With persistence enabled
+// every write runs the commit protocol — persist → apply → ack — so the ack
+// means durable AND applied (see fastsandbox_policy_persist.go).
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+
+ "github.com/alibaba/opensandbox/egress/pkg/actionhandler"
+ "github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/log"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// policyEntry records the per-subject policy bookkeeping: the revision the
+// relay preconditions fence on, the runtime fence the record was
+// materialized under, and the two state flags. The policy itself lives in
+// the registry (active subjects) or pendingPolicies (denying subjects).
+type policyEntry struct {
+ revision int64
+ fence subject.Fencing
+ // hydrated marks a record loaded from the persisted policy file: the
+ // binding input no longer drives this subject's policy — the file (and
+ // the relay writes on top of it) is authoritative, exactly like the
+ // vault slice. Sticky for the record's lifetime.
+ hydrated bool
+ // sealed marks a paused subject whose policy file was exported into the
+ // snapshot bundle: every relay op answers 409; enforcement is unchanged.
+ sealed bool
+}
+
+// policyRelayDocument is the GET response and PUT body of the relay
+// surface. Revision is echoed by GET and acts as the PUT precondition (the
+// GET body is re-pushable verbatim); ExpectedRevision is the explicit
+// precondition form. Both present must agree.
+type policyRelayDocument struct {
+ Revision int64 `json:"revision"`
+ ExpectedRevision *int64 `json:"expectedRevision,omitempty"`
+ Policy json.RawMessage `json:"policy"`
+}
+
+// maxPolicyRelayBodyBytes bounds one relay body: the policy (the platform
+// binding-input cap) plus the document framing.
+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)
+ if !validVaultSubjectID(uid) {
+ http.Error(w, "missing or invalid sandbox uid in path", http.StatusBadRequest)
+ return
+ }
+ subj := subject.FromSandboxUID(uid)
+ switch r.Method {
+ case http.MethodGet:
+ doc, status, msg := s.selectRelayPolicy(r, subj)
+ if status != 0 {
+ http.Error(w, msg, status)
+ return
+ }
+ writeJSON(w, http.StatusOK, doc)
+ case http.MethodPut, http.MethodDelete:
+ s.handlePolicyRelayWrite(w, r, subj)
+ default:
+ w.Header().Set("Allow", "GET, PUT, DELETE")
+ http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+ }
+}
+
+// selectRelayPolicy decides registration, the expectedIncarnation
+// precondition, the seal, and the recorded policy under one s.mu hold. A
+// status other than zero means the caller must write (status, msg).
+func (s *fastSandboxPolicyServer) selectRelayPolicy(r *http.Request, subj subject.Subject) (*policyRelayDocument, int, string) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ fence, ok := s.reg.Fence(subj)
+ if !ok {
+ return nil, http.StatusNotFound, "unknown subject"
+ }
+ if inc := strings.TrimSpace(r.Header.Get(constants.EgressVaultIncarnationHeader)); inc != "" && inc != fence.RuntimeInstanceID {
+ return nil, http.StatusPreconditionFailed, "expectedIncarnation mismatch"
+ }
+ if e := s.policies[subj]; e != nil && e.sealed {
+ return nil, http.StatusConflict, "subject policy is sealed (paused); the bundle copy is already taken"
+ }
+ pol := s.reg.UserPolicy(subj)
+ if pol == nil {
+ pol = s.pendingPolicies[subj]
+ }
+ if pol == nil {
+ return nil, http.StatusNotFound, "subject has no recorded policy"
+ }
+ rev := int64(0)
+ if e := s.policies[subj]; e != nil {
+ rev = e.revision
+ }
+ raw, err := json.Marshal(pol)
+ if err != nil {
+ return nil, http.StatusInternalServerError, "policy serialization failure"
+ }
+ return &policyRelayDocument{Revision: rev, Policy: raw}, 0, ""
+}
+
+// handlePolicyRelayWrite serves PUT (full replace, create-when-absent) and
+// DELETE (revert to deny-first).
+//
+// The body is parsed and the policy validated BEFORE the commit serialization
+// is taken: a stalled or invalid client must never hold it. Guards run under
+// s.mu; the commit protocol itself serializes per process on
+// policyCommitMu (the Fastlet serializes same-UID actions, but relayed
+// writers from server replicas do not serialize with each other), and the
+// apply closures take s.mu only for the bookkeeping maps — never around
+// enforcement, which takes the registry write lock.
+func (s *fastSandboxPolicyServer) handlePolicyRelayWrite(w http.ResponseWriter, r *http.Request, subj subject.Subject) {
+ var doc policyRelayDocument
+ if r.Method == http.MethodPut {
+ data, err := io.ReadAll(io.LimitReader(r.Body, maxPolicyRelayBodyBytes+1))
+ if err != nil {
+ http.Error(w, "failed to read policy body: "+err.Error(), http.StatusBadRequest)
+ return
+ }
+ if len(data) > maxPolicyRelayBodyBytes {
+ http.Error(w, fmt.Sprintf("policy body exceeds %d bytes", maxPolicyRelayBodyBytes), http.StatusBadRequest)
+ return
+ }
+ dec := json.NewDecoder(strings.NewReader(string(data)))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&doc); err != nil {
+ http.Error(w, "invalid policy replace request: "+err.Error(), http.StatusBadRequest)
+ return
+ }
+ }
+ // The body has been consumed; a late response must not try to read it.
+ r.Body.Close()
+
+ if r.Method == http.MethodPut && len(doc.Policy) == 0 {
+ http.Error(w, "policy body required", http.StatusBadRequest)
+ return
+ }
+ pol, err := policy.ParsePolicy(string(doc.Policy))
+ if err != nil {
+ http.Error(w, "invalid policy: "+err.Error(), http.StatusBadRequest)
+ return
+ }
+ expected, perr := relayPolicyPrecondition(&doc)
+ if perr != nil {
+ http.Error(w, perr.Error(), http.StatusBadRequest)
+ return
+ }
+
+ // Serialize the whole write — guards, decision, and commit — per
+ // process on policyCommitMu: the Fastlet serializes same-UID actions,
+ // but relayed writers from server replicas do not serialize with each
+ // other or with a concurrent SET_BINDING commit. The decision must be
+ // commit-atomic or two racing replaces could land the same revision.
+ // The ordering policyCommitMu → s.mu is the commit path's; enforcement
+ // in the apply closures never runs under s.mu.
+ s.policyCommitMu.Lock()
+ defer s.policyCommitMu.Unlock()
+
+ // Guards + decision under one s.mu hold, serialized against rebinds and
+ // terminal purges.
+ s.mu.Lock()
+ fence, ok := s.reg.Fence(subj)
+ if !ok {
+ s.mu.Unlock()
+ http.Error(w, "unknown subject", http.StatusNotFound)
+ return
+ }
+ if inc := strings.TrimSpace(r.Header.Get(constants.EgressVaultIncarnationHeader)); inc != "" && inc != fence.RuntimeInstanceID {
+ s.mu.Unlock()
+ http.Error(w, "expectedIncarnation mismatch", http.StatusPreconditionFailed)
+ return
+ }
+ entry := s.policies[subj]
+ if entry != nil && entry.sealed {
+ s.mu.Unlock()
+ http.Error(w, "subject policy is sealed (paused); the bundle copy is already taken", http.StatusConflict)
+ return
+ }
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ s.mu.Unlock()
+ http.Error(w, "policy persistence recovery required: "+recovery.reason, http.StatusServiceUnavailable)
+ return
+ }
+ cur := int64(0)
+ if entry != nil {
+ cur = entry.revision
+ }
+ state, _ := s.reg.Get(subj)
+ stateActive := state == subject.StateActive
+ att, attOK := s.subjAtt[subj]
+ s.mu.Unlock()
+
+ if r.Method == http.MethodDelete {
+ if entry == nil {
+ http.Error(w, "subject has no recorded policy", http.StatusNotFound)
+ return
+ }
+ s.deleteRelayPolicy(w, subj, fence, att, attOK, stateActive)
+ return
+ }
+
+ // PUT: a conditional replace against an absent record is a 412, not a
+ // create (sidecar parity).
+ if expected != nil && entry == nil {
+ http.Error(w, "expectedRevision mismatch", http.StatusPreconditionFailed)
+ return
+ }
+ if expected != nil && *expected != cur {
+ http.Error(w, "expectedRevision mismatch", http.StatusPreconditionFailed)
+ return
+ }
+ created := entry == nil
+ newRev := cur + 1
+ s.putRelayPolicy(w, r, subj, fence, pol, newRev, created, entry, stateActive)
+}
+
+// relayPolicyPrecondition extracts the effective precondition. The revision
+// echoed by GET and an explicit expectedRevision must agree when both are
+// present (ambiguous request).
+func relayPolicyPrecondition(doc *policyRelayDocument) (expected *int64, err error) {
+ switch {
+ case doc.ExpectedRevision == nil:
+ if doc.Revision != 0 {
+ rev := doc.Revision
+ expected = &rev
+ }
+ case doc.Revision == 0 || doc.Revision == *doc.ExpectedRevision:
+ expected = doc.ExpectedRevision
+ default:
+ err = fmt.Errorf("revision %d and expectedRevision %d disagree", doc.Revision, *doc.ExpectedRevision)
+ }
+ return expected, err
+}
+
+// putRelayPolicy commits a full replace: persist → apply → ack, so the ack
+// means durable AND applied. The caller holds policyCommitMu (the decision
+// and the commit are one serialized unit). The live entry keeps its
+// hydrated flag — a relay write on a file-backed record stays file-backed.
+func (s *fastSandboxPolicyServer) putRelayPolicy(w http.ResponseWriter, r *http.Request, subj subject.Subject, fence subject.Fencing, pol *policy.NetworkPolicy, newRev int64, created bool, entry *policyEntry, stateActive bool) {
+ raw, err := json.Marshal(pol)
+ if err != nil {
+ log.Errorf("subject %s: policy marshal failed: %v", subj, err)
+ http.Error(w, "policy persistence failure", http.StatusInternalServerError)
+ return
+ }
+ doc := policyRelayDocument{Revision: newRev, Policy: raw}
+
+ apply := func() error {
+ if stateActive {
+ // Enforcement first: a failed apply leaves the record untouched
+ // (the commit protocol rolls the file back).
+ if err := s.applyPolicy(subj, pol); err != nil {
+ return err
+ }
+ }
+ s.mu.Lock()
+ if !stateActive {
+ s.pendingPolicies[subj] = pol
+ }
+ hydrated := entry != nil && entry.hydrated
+ s.policies[subj] = &policyEntry{revision: newRev, fence: fence, hydrated: hydrated}
+ s.mu.Unlock()
+ return nil
+ }
+
+ if s.policyFiles == nil {
+ // Memory-only (persistence disabled): direct commit.
+ if err := apply(); err != nil {
+ http.Error(w, "policy apply failure", http.StatusInternalServerError)
+ return
+ }
+ writeJSON(w, putResponseStatus(created), doc)
+ return
+ }
+ payload, err := policy.EncodePolicyFile(fence.RuntimeInstanceID, fence.AttachmentID, newRev, raw)
+ if err != nil {
+ log.Errorf("subject %s: policy file encode failed: %v", subj, err)
+ http.Error(w, "policy persistence failure", http.StatusInternalServerError)
+ return
+ }
+ err = s.persistPolicyCandidateLocked(
+ subj,
+ func(fs vaultFileStore) (policy.FileMutationState, error) {
+ return fs.SaveRaw(payload)
+ },
+ apply,
+ )
+ if err != nil {
+ // Uncertain persist latched → 503; every other failure kept last-good
+ // on both sides → retryable 500. Details stay in the log.
+ log.Errorf("subject %s: policy relay write failed: %v", subj, err)
+ status := http.StatusInternalServerError
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ status = http.StatusServiceUnavailable
+ }
+ http.Error(w, "policy persistence failure", status)
+ return
+ }
+ writeJSON(w, putResponseStatus(created), doc)
+}
+
+// putResponseStatus maps the committed replace onto the relay contract:
+// 201 when it created the record, 200 otherwise.
+func putResponseStatus(created bool) int {
+ if created {
+ return http.StatusCreated
+ }
+ return http.StatusOK
+}
+
+// deleteRelayPolicy commits the revert to deny-first: memory and file go
+// together, so a restart cannot resurrect a deleted policy. The caller
+// holds policyCommitMu.
+func (s *fastSandboxPolicyServer) deleteRelayPolicy(w http.ResponseWriter, subj subject.Subject, fence subject.Fencing, att actionhandler.NetworkAttachment, attOK, stateActive bool) {
+ apply := func() error {
+ if stateActive {
+ // Enforcement first: nft deny-first commits before the registry
+ // state (fail-closed transition), mirroring SET_BINDING removal.
+ if !attOK {
+ return fmt.Errorf("subject %s has no recorded attachment for the deny-first revert", subj)
+ }
+ if err := s.revertToDenyFirst(subj, att); err != nil {
+ return err
+ }
+ }
+ s.mu.Lock()
+ delete(s.pendingPolicies, subj)
+ delete(s.policies, subj)
+ s.mu.Unlock()
+ return nil
+ }
+
+ if s.policyFiles == nil {
+ if err := apply(); err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ w.WriteHeader(http.StatusNoContent)
+ return
+ }
+ err := s.persistPolicyCandidateLocked(
+ subj,
+ func(fs vaultFileStore) (policy.FileMutationState, error) {
+ return fs.Delete()
+ },
+ apply,
+ )
+ if err != nil {
+ log.Errorf("subject %s: policy relay delete failed: %v", subj, err)
+ status := http.StatusInternalServerError
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ status = http.StatusServiceUnavailable
+ }
+ http.Error(w, "policy persistence failure", status)
+ return
+ }
+ log.Infof("subject %s: policy deleted (deny-first), record purged", subj)
+ w.WriteHeader(http.StatusNoContent)
+}
+
+// writePolicyRelayWriteResponse maps the committed mutation onto the relay
+// contract: PUT → 200 (201 when it created), DELETE → 204.
+func writePolicyRelayWriteResponse(w http.ResponseWriter, r *http.Request, revision int64, created bool) {
+ if r.Method == http.MethodDelete {
+ w.WriteHeader(http.StatusNoContent)
+ return
+ }
+ status := http.StatusOK
+ if created {
+ status = http.StatusCreated
+ }
+ writeJSON(w, status, policyRelayDocument{Revision: revision, Policy: json.RawMessage("null")})
+}
diff --git a/components/egress/fastsandbox_policy_persist.go b/components/egress/fastsandbox_policy_persist.go
new file mode 100644
index 000000000..417c11c07
--- /dev/null
+++ b/components/egress/fastsandbox_policy_persist.go
@@ -0,0 +1,452 @@
+// 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.
+
+// Egress-held policy persistence: one file per subject under
+// <egress-volume>/policy/, mirroring the vault persistence machinery
+// (fastsandbox_vault_persist.go). The recorded policy is the recovery
+// source for an egress restart — at SET_BINDING replay the committed file
+// supersedes the replayed binding input, which carries only the original
+// bootstrap policy — and the bundle source for the POLICY_EXPORT /
+// POLICY_IMPORT snapshot transfer. Ordering is persist → apply → ack
+// (acked ⇒ durable and applied), with the same three-state classification,
+// snapshot restore, and recovery latch as the vault files.
+package main
+
+import (
+ "encoding/json"
+ "errors"
+ "fmt"
+ "os"
+ "path/filepath"
+ "sync"
+
+ "github.com/alibaba/opensandbox/egress/pkg/log"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// policyRecoveryState is the recovery latch payload.
+type policyRecoveryState struct {
+ reason string
+}
+
+// policyPersistence owns the per-subject policy files: <dir>/<sandboxUid>.json,
+// with lazily constructed, cached file stores. The file store seam is the
+// same vaultFileStore contract — one atomic-file abstraction serves both
+// state kinds.
+type policyPersistence struct {
+ dir string
+ // newFile is injectable for tests; the default is the atomic file machinery.
+ newFile func(path string) (vaultFileStore, error)
+
+ mu sync.Mutex
+ files map[subject.Subject]vaultFileStore
+}
+
+// newPolicyPersistence prepares the policy directory (0700) and sweeps
+// staged leftovers: startup loads the committed files only.
+func newPolicyPersistence(dir string) (*policyPersistence, error) {
+ if err := prepareStateDir(dir, "policy"); err != nil {
+ return nil, err
+ }
+ return &policyPersistence{
+ dir: dir,
+ newFile: func(path string) (vaultFileStore, error) { return policy.NewAtomicPolicyFile(path) },
+ files: make(map[subject.Subject]vaultFileStore),
+ }, nil
+}
+
+func (p *policyPersistence) pathFor(subj subject.Subject) (string, error) {
+ uid := vaultFileUID(subj)
+ // The relay validates the path-derived UID; envelope UIDs get the same check.
+ if !validVaultSubjectID(uid) {
+ return "", fmt.Errorf("subject uid %q cannot name a policy file", uid)
+ }
+ return filepath.Join(p.dir, uid+".json"), nil
+}
+
+// storeFor returns the subject's file store, constructing it on first use.
+func (p *policyPersistence) storeFor(subj subject.Subject) (vaultFileStore, error) {
+ p.mu.Lock()
+ defer p.mu.Unlock()
+ if fs, ok := p.files[subj]; ok {
+ return fs, nil
+ }
+ path, err := p.pathFor(subj)
+ if err != nil {
+ return nil, err
+ }
+ fs, err := p.newFile(path)
+ if err != nil {
+ return nil, err
+ }
+ p.files[subj] = fs
+ return fs, nil
+}
+
+// purge removes the subject's file and evicts the cached store. An
+// already-absent file is a complete purge; an uncertain outcome is reported —
+// the leftover stays fenced out by its recorded runtime fence either way.
+// The seal marker (if any) goes with it.
+func (p *policyPersistence) purge(subj subject.Subject) error {
+ fs, err := p.storeFor(subj)
+ if err != nil {
+ return err
+ }
+ state, err := fs.Delete()
+ if err == nil || state == policy.FileUnchanged {
+ p.mu.Lock()
+ delete(p.files, subj)
+ p.mu.Unlock()
+ }
+ if err != nil {
+ return err
+ }
+ if state == policy.FileUnknown {
+ return errors.New("policy file unlink outcome uncertain")
+ }
+ return p.unseal(subj)
+}
+
+// markerFor names the durable seal marker: export writes it before acking
+// sealed, and a handler restart between export and REMOVE_BINDING restores
+// the seal from it — otherwise binding replay would treat the bundle-backed
+// state as live while the bundle copy is already taken.
+func (p *policyPersistence) markerFor(subj subject.Subject) (string, error) {
+ path, err := p.pathFor(subj)
+ if err != nil {
+ return "", err
+ }
+ return path + ".sealed", nil
+}
+
+// seal writes the marker durably. Presence is the signal; no fsync — the
+// marker only needs to survive a container restart, and a torn write still
+// exists.
+func (p *policyPersistence) seal(subj subject.Subject) error {
+ path, err := p.markerFor(subj)
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(path, []byte("sealed"), 0o600)
+}
+
+// unseal removes the marker; an absent marker is a complete unseal.
+func (p *policyPersistence) unseal(subj subject.Subject) error {
+ path, err := p.markerFor(subj)
+ if err != nil {
+ return err
+ }
+ if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
+ return err
+ }
+ return nil
+}
+
+// isSealed reports whether the durable seal marker exists.
+func (p *policyPersistence) isSealed(subj subject.Subject) bool {
+ path, err := p.markerFor(subj)
+ if err != nil {
+ return false
+ }
+ _, err = os.Stat(path)
+ return err == nil
+}
+
+// reservesPath reports whether a driver-provided snapshot path resolves
+// inside the policy persistence directory — reserved for per-subject policy
+// files (an export target there could clobber another subject's policy).
+func (p *policyPersistence) reservesPath(path string) bool {
+ return reservesPathUnder(p.dir, path)
+}
+
+// SetPolicyFiles wires persistence under the relay handlers; nil (the
+// default) keeps the policy memory-only.
+func (s *fastSandboxPolicyServer) SetPolicyFiles(pp *policyPersistence) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.policyFiles = pp
+}
+
+// purgePolicyFile removes the subject's persisted policy (rebind or terminal
+// cleanup). Best effort: a failed purge leaves a file that its recorded
+// fence keeps out of every later registration.
+func (s *fastSandboxPolicyServer) purgePolicyFile(subj subject.Subject) {
+ if s.policyFiles == nil {
+ return
+ }
+ if err := s.policyFiles.purge(subj); err != nil {
+ log.Errorf("subject %s: policy file purge failed (leftover stays fenced out): %v", subj, err)
+ }
+}
+
+// persistPolicyCandidateLocked runs the commit protocol; the caller
+// serializes per-subject writers on policyCommitMu for the whole operation
+// (relay writes and SET_BINDING commits both take it). persist performs the
+// durable effect and returns its three-state classification; apply commits
+// the memory mutation and must leave the live state untouched on failure (a
+// failed apply only needs the file rolled back). The apply closure must not
+// hold s.mu around enforcement (applyPolicy takes the registry write lock,
+// which serializes against takeover paths that take s.mu).
+func (s *fastSandboxPolicyServer) persistPolicyCandidateLocked(
+ subj subject.Subject,
+ persist func(vaultFileStore) (policy.FileMutationState, error),
+ apply func() error,
+) error {
+ fs, err := s.policyFiles.storeFor(subj)
+ if err != nil {
+ return fmt.Errorf("policy file store unavailable: %w", err)
+ }
+ before, err := fs.Snapshot()
+ if err != nil {
+ return fmt.Errorf("policy file snapshot: %w", err)
+ }
+ state, err := persist(fs)
+ switch {
+ case err == nil && state == policy.FileCommitted:
+ // Rename + parent-dir fsync done.
+ case err == nil && state == policy.FileUnchanged:
+ // Delete of an already-absent file (SaveRaw never returns this pair).
+ case err == nil:
+ // A success that did not confirm an effect is uncertain.
+ state = policy.FileUnknown
+ err = errors.New("policy file persist did not confirm durable completion")
+ }
+ if err != nil && state == policy.FileUnchanged {
+ // Pre-rename failure: last-good intact — NACK without restore or latch.
+ return err
+ }
+ if err != nil {
+ // Publication attempted, durability unconfirmed: latch first (only a
+ // restart reconciles), then restore so disk agrees with the untouched
+ // live state.
+ s.requirePolicyRecoveryLocked("policy file persist outcome uncertain")
+ if restoreErr := restoreVaultFile(fs, before); restoreErr != nil {
+ log.Errorf("subject %s: policy file restore after uncertain persist: %v", subj, restoreErr)
+ return fmt.Errorf("%w (restore also failed: %v)", err, restoreErr)
+ }
+ return err
+ }
+ // Durable. A failed apply rolls the file back — no latch while the
+ // restore is confirmed.
+ if applyErr := apply(); applyErr != nil {
+ if restoreErr := restoreVaultFile(fs, before); restoreErr != nil {
+ s.requirePolicyRecoveryLocked("policy file restore after failed apply was inconclusive")
+ log.Errorf("subject %s: policy file restore after failed apply: %v", subj, restoreErr)
+ return fmt.Errorf("policy apply failed (%v) and restore failed (%v)", applyErr, restoreErr)
+ }
+ return fmt.Errorf("policy apply: %w", applyErr)
+ }
+ return nil
+}
+
+// requirePolicyRecoveryLocked latches recovery (first reason wins): policy
+// writes freeze until the process restarts and reconciles from the committed
+// files. The latch is an atomic so the healthz probe reads it lock-free.
+func (s *fastSandboxPolicyServer) requirePolicyRecoveryLocked(reason string) {
+ if s.policyRecovery.Load() == nil {
+ s.policyRecovery.CompareAndSwap(nil, &policyRecoveryState{reason: reason})
+ log.Errorf("policy persistence recovery latched (writes frozen until restart): %s", reason)
+ }
+}
+
+// policyRecoveryActive reports whether the recovery latch freezes writes.
+func (s *fastSandboxPolicyServer) policyRecoveryActive() bool {
+ return s.policyRecovery.Load() != nil
+}
+
+// policyHealthIssue is non-empty only for the process-level failure — the
+// recovery latch.
+func (s *fastSandboxPolicyServer) policyHealthIssue() string {
+ if state := s.policyRecovery.Load(); state != nil {
+ return "policy persistence recovery required: " + state.reason
+ }
+ return ""
+}
+
+// clearPolicyRecord removes the subject's recorded policy (binding removal
+// on a still-live sandbox): the entry goes and the persisted file is purged,
+// so the deny-first state is also the durable state — a restart cannot
+// resurrect a removed policy, and a later registration starts from its own
+// binding input.
+func (s *fastSandboxPolicyServer) clearPolicyRecord(subj subject.Subject) {
+ s.mu.Lock()
+ delete(s.policies, subj)
+ s.mu.Unlock()
+ s.purgePolicyFile(subj)
+}
+
+// rehydratePolicyReload is the egress-restart recovery path: at
+// (re)registration of a subject with no recorded policy entry, load its
+// committed file, fenced by the full runtime identity:
+//
+// - fence match → the file is authoritative — the replayed binding input
+// carries only the original bootstrap policy, never the relay mutations
+// recorded since — and the entry materializes file-backed (hydrated)
+// - mismatch → stale, purged (a reset never inherits the predecessor's
+// policy)
+// - unreadable, a newer schema, or content that fails to parse → the file
+// is quarantined and the binding input seeds the subject. Unlike the
+// vault (whose content has no fallback source), a policy this egress
+// cannot read has a safe fallback: the replayed binding input is the
+// create-time bootstrap, so it can never grant post-create relay
+// mutations
+//
+// Removal SET_BINDINGS skip the reload (clearPolicyRecord handles them).
+// A live record for this exact fence wins (duplicate SET_BINDING); one left
+// under a different fence goes through the file rules as a fresh
+// registration. The reload runs BEFORE RegisterAndEnforce so no concurrent
+// action can materialize state ahead of it, mirroring rehydrateVaultReload;
+// a failed registration leaves the reloaded pending policy on a denying
+// subject, which the Fastlet's retry converges.
+func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fence subject.Fencing) {
+ if s.policyFiles == nil {
+ return
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if e := s.policies[subj]; e != nil {
+ if e.fence == fence {
+ return
+ }
+ delete(s.policies, subj)
+ }
+ fs, err := s.policyFiles.storeFor(subj)
+ if err != nil {
+ log.Warnf("subject %s: policy file store unavailable (%v); the binding input seeds the subject", subj, err)
+ return
+ }
+ snap, err := fs.Snapshot()
+ if err != nil {
+ log.Warnf("subject %s: policy file unreadable (%v); the binding input seeds the subject", subj, err)
+ return
+ }
+ if !snap.Exists() {
+ // Fresh subject: nothing persisted, the binding input seeds.
+ return
+ }
+ pf, body, decErr := policy.DecodePolicyFile(snap.Data())
+ if decErr != nil {
+ if _, delErr := fs.Delete(); delErr != nil {
+ log.Errorf("subject %s: unreadable policy file quarantine failed (file left in place): %v", subj, delErr)
+ return
+ }
+ log.Warnf("subject %s: policy file unusable (%v); quarantined, the binding input seeds the subject", subj, decErr)
+ return
+ }
+ recorded := subject.Fencing{RuntimeInstanceID: pf.Incarnation, AttachmentID: pf.AttachmentID}
+ if !recorded.Matches(fence) {
+ // Stale: discard durably. A failed purge is harmless — the recorded
+ // fence mismatches every later registration regardless.
+ if _, delErr := fs.Delete(); delErr != nil {
+ log.Warnf("subject %s: stale policy file purge failed (stays fenced out): %v", subj, delErr)
+ } else {
+ log.Infof("subject %s: stale policy file discarded (fence %s/%s ≠ %s/%s)", subj, pf.Incarnation, pf.AttachmentID, fence.RuntimeInstanceID, fence.AttachmentID)
+ }
+ return
+ }
+ pol, parseErr := policy.ParsePolicy(string(body))
+ if parseErr != nil {
+ if _, delErr := fs.Delete(); delErr != nil {
+ log.Errorf("subject %s: unparseable policy file quarantine failed (file left in place): %v", subj, delErr)
+ return
+ }
+ log.Warnf("subject %s: policy file content rejected (%v); quarantined, the binding input seeds the subject", subj, parseErr)
+ return
+ }
+ entry := &policyEntry{revision: pf.Revision, fence: fence, hydrated: true}
+ // A durable seal marker (export acked, teardown not yet delivered)
+ // restores the sealed entry across a restart: relay ops stay 409 until
+ // REMOVE_BINDING purges or an import unseals.
+ if s.policyFiles.isSealed(subj) {
+ entry.sealed = true
+ log.Infof("subject %s: policy seal restored from marker (exported bundle pending)", subj)
+ }
+ s.policies[subj] = entry
+ s.pendingPolicies[subj] = pol
+ log.Infof("subject %s: policy reloaded from file (revision %d, incarnation %s); binding input superseded", subj, pf.Revision, pf.Incarnation)
+}
+
+// applyBindingPolicy installs the binding's policy for a registered subject.
+// It is the SET_BINDING tail counterpart of the relay writes and runs the
+// same commit protocol. The binding input keeps its authority only while the
+// subject's record is not file-backed: once the policy was rehydrated from
+// the persisted file, later binding replays (which carry only the bootstrap
+// input) never override the recorded state, and a sealed record never moves
+// (the bundle copy is taken).
+func (s *fastSandboxPolicyServer) applyBindingPolicy(subj subject.Subject, fence subject.Fencing, pol *policy.NetworkPolicy, stateActive bool) error {
+ s.policyCommitMu.Lock()
+ defer s.policyCommitMu.Unlock()
+
+ s.mu.Lock()
+ entry := s.policies[subj]
+ var (
+ rev int64
+ commit bool
+ )
+ switch {
+ case entry != nil && entry.sealed:
+ // Exported: the bundle copy is taken; the recorded state is frozen.
+ case entry != nil && entry.hydrated:
+ // File-backed: the binding input carries no authority.
+ case entry != nil:
+ rev, commit = entry.revision+1, true
+ default:
+ rev, commit = 1, true
+ }
+ pp := s.policyFiles
+ s.mu.Unlock()
+
+ if !commit {
+ log.Infof("subject %s: binding input superseded by the recorded policy (revision %d)", subj, entry.revision)
+ return nil
+ }
+
+ raw, err := json.Marshal(pol)
+ if err != nil {
+ return fmt.Errorf("policy marshal: %w", err)
+ }
+ apply := func() error {
+ if stateActive {
+ // Enforcement first: a failed apply leaves the record untouched
+ // (the commit protocol rolls the file back). Called without
+ // s.mu — it takes the registry write lock.
+ if err := s.applyPolicy(subj, pol); err != nil {
+ return err
+ }
+ }
+ s.mu.Lock()
+ if !stateActive {
+ s.pendingPolicies[subj] = pol
+ }
+ s.policies[subj] = &policyEntry{revision: rev, fence: fence}
+ s.mu.Unlock()
+ return nil
+ }
+ if pp == nil {
+ // Memory-only: direct commit.
+ return apply()
+ }
+ payload, err := policy.EncodePolicyFile(fence.RuntimeInstanceID, fence.AttachmentID, rev, raw)
+ if err != nil {
+ return fmt.Errorf("policy file encode: %w", err)
+ }
+ return s.persistPolicyCandidateLocked(
+ subj,
+ func(fs vaultFileStore) (policy.FileMutationState, error) {
+ return fs.SaveRaw(payload)
+ },
+ apply,
+ )
+}
diff --git a/components/egress/fastsandbox_policy_persist_test.go b/components/egress/fastsandbox_policy_persist_test.go
new file mode 100644
index 000000000..6e6c6e9df
--- /dev/null
+++ b/components/egress/fastsandbox_policy_persist_test.go
@@ -0,0 +1,470 @@
+// 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/json"
+ "errors"
+ "fmt"
+ "net/http"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "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"
+)
+
+// Policy persistence: the recorded policy survives an egress restart and
+// supersedes the replayed binding input. Outcomes are substituted at the
+// same vaultFileStore seam the vault tests use.
+
+// policyPersistHarness wires a fast-sandbox test server to fake-backed
+// policy persistence over a real (swept) temp directory.
+type policyPersistHarness struct {
+ srv *fastSandboxPolicyServer
+ reg *subject.MemoryRegistry
+ nft *fakeNft
+ pp *policyPersistence
+ dir string
+ files map[string]*fakeVaultFile
+}
+
+func newPolicyPersistHarness(t *testing.T) *policyPersistHarness {
+ t.Helper()
+ dir := t.TempDir()
+ h := &policyPersistHarness{files: make(map[string]*fakeVaultFile), dir: dir}
+ h.srv, h.reg, h.nft = fastSandboxTestServer(t)
+ pp, err := newPolicyPersistence(dir)
+ require.NoError(t, err)
+ pp.newFile = func(path string) (vaultFileStore, error) {
+ f, ok := h.files[path]
+ if !ok {
+ f = newFakeVaultFile(path)
+ h.files[path] = f
+ }
+ return f, nil
+ }
+ h.pp = pp
+ h.srv.SetPolicyFiles(pp)
+ return h
+}
+
+// readySubject drives SET_BINDING + both hooks under the default test fence.
+func (h *policyPersistHarness) readySubject(t *testing.T, uid, ip string) subject.Subject {
+ t.Helper()
+ s := subject.FromSandboxUID(uid)
+ rec := doAction(t, h.srv, bindBody(t, uid, ip, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, uid, testFenceR, testFenceA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, uid, testFenceR, testFenceA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ return s
+}
+
+func (h *policyPersistHarness) fileFor(uid string) *fakeVaultFile {
+ path := filepath.Join(h.dir, uid+".json")
+ f, ok := h.files[path]
+ if !ok {
+ f = newFakeVaultFile(path)
+ h.files[path] = f
+ }
+ return f
+}
+
+// fakeForPath returns (creating if needed) the fake store for an arbitrary
+// path — policy files and bundle staging files share the newFile seam.
+func (h *policyPersistHarness) fakeForPath(path string) *fakeVaultFile {
+ f, ok := h.files[path]
+ if !ok {
+ f = newFakeVaultFile(path)
+ h.files[path] = f
+ }
+ return f
+}
+
+// seedPolicyFile writes simulated committed file bytes before registration.
+func (h *policyPersistHarness) seedPolicyFile(t *testing.T, uid, incarnation, attachment string, revision int64, policyBody string) {
+ t.Helper()
+ raw, err := policy.EncodePolicyFile(incarnation, attachment, revision, json.RawMessage(policyBody))
+ require.NoError(t, err)
+ f := h.fileFor(uid)
+ f.data = raw
+ f.exists = true
+}
+
+// decodePolicyFile decodes the simulated file bytes of a subject.
+func decodePolicyFile(t *testing.T, f *fakeVaultFile) (policy.PolicyFile, json.RawMessage) {
+ t.Helper()
+ require.True(t, f.exists, "the policy file must exist")
+ pf, body, err := policy.DecodePolicyFile(f.data)
+ require.NoError(t, err)
+ return pf, body
+}
+
+// seedPolicyBundle writes a real bundle file carrying the OLD runtime fence
+// (import reads the source with plain I/O — no injected seam).
+func (h *policyPersistHarness) seedPolicyBundle(t *testing.T, path string, revision int64, policyBody string) []byte {
+ t.Helper()
+ raw, err := policy.EncodePolicyFile(testFenceR, testFenceA, revision, json.RawMessage(policyBody))
+ require.NoError(t, err)
+ require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o700))
+ require.NoError(t, os.WriteFile(path, raw, 0o600))
+ return raw
+}
+
+// policySnapshotBody builds a POLICY_EXPORT / POLICY_IMPORT envelope.
+func policySnapshotBody(t *testing.T, uid, runtimeID, attID, op, path string) string {
+ t.Helper()
+ env := actionhandler.Envelope{
+ APIVersion: constants.ActionsAPIVersion,
+ Operation: actionhandler.Operation(op),
+ InvocationID: fmt.Sprintf("inv-%s-policy-snapshot", uid),
+ Sandbox: actionhandler.SandboxRef{UID: uid, Name: "sb", Namespace: "ns"},
+ Revision: actionhandler.Revision{
+ SpecGeneration: 1,
+ RuntimeInstanceID: runtimeID,
+ AttachmentID: attID,
+ RouteGeneration: 1,
+ },
+ Snapshot: &actionhandler.SnapshotTransfer{Path: path},
+ }
+ raw, err := json.Marshal(env)
+ require.NoError(t, err)
+ return string(raw)
+}
+
+// ---------------------------------------------------------------------------
+// SET_BINDING seeds and persists the record
+// ---------------------------------------------------------------------------
+
+func TestPolicyPersistSetBindingStampsFile(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+
+ pf, body := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, 1, pf.Version)
+ assert.Equal(t, testFenceR, pf.Incarnation)
+ assert.Equal(t, testFenceA, pf.AttachmentID)
+ assert.Equal(t, int64(1), pf.Revision)
+ assert.Contains(t, string(body), "api.example.com")
+
+ // GET serves the seeded policy + revision.
+ rec := doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+
+ // A relay write persists the successor revision.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ pf, body = decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, int64(2), pf.Revision)
+ assert.Contains(t, string(body), "other.example.com")
+}
+
+// ---------------------------------------------------------------------------
+// Reload at SET_BINDING (egress-restart recovery): the file wins
+// ---------------------------------------------------------------------------
+
+func TestPolicyPersistReloadSupersedesBindingInput(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+
+ // Committed state from the previous egress generation: revision 5
+ // carrying a relay mutation (other.example.com). The replayed binding
+ // input still carries the bootstrap policy (api.example.com).
+ h.seedPolicyFile(t, policyTestUID, testFenceR, testFenceA, 5, policyAllowAlt())
+
+ rec := doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The file is authoritative: the recorded policy serves at revision 5
+ // and the binding input is superseded.
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(5), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+ assert.NotContains(t, string(doc.Policy), "api.example.com")
+
+ // data-plane-ready activates the RELOADED policy.
+ rec = doAction(t, h.srv, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(h.srv, s, "other.example.com"))
+ assert.Equal(t, "deny", reg_UserEvaluate(h.srv, s, "api.example.com"))
+
+ // A replayed binding with the bootstrap input does not override the
+ // file-backed record.
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc = mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(5), rev, "a file-backed record never moves for a binding replay")
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+
+ // A relay write on the file-backed record works and stays file-backed.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 5, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, int64(6), pf.Revision)
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 3, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, _ = mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(6), rev, "relay writes keep the record file-backed")
+}
+
+// TestPolicyPersistRestartRecoversRelayWrites: simulate an egress restart —
+// a fresh server over the same persistence state — and verify the relayed
+// policy survives the binding replay.
+func TestPolicyPersistRestartRecoversRelayWrites(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+
+ // Runtime mutation via the relay: revision 2.
+ rec := doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Fresh server over the same persistence state (the fake-backed files
+ // simulate the disk and survive), then the Fastlet's binding replay.
+ srv2, _, _ := fastSandboxTestServer(t)
+ pp2, err := newPolicyPersistence(h.dir)
+ require.NoError(t, err)
+ pp2.newFile = h.pp.newFile
+ srv2.SetPolicyFiles(pp2)
+
+ rec = doAction(t, srv2, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, srv2, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, srv2, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The relayed policy survived the restart.
+ rec = doPolicy(t, srv2, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(2), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(srv2, s, "other.example.com"))
+}
+
+func TestPolicyPersistStaleIncarnationDiscarded(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+
+ // A reset: the file belongs to a previous runtime instance.
+ h.seedPolicyFile(t, policyTestUID, "runtime-0", "attachment-0", 5, policyAllowAlt())
+
+ h.readySubject(t, policyTestUID, vaultTestIP)
+
+ // Stale, discarded: the successor is seeded from its binding input and
+ // the file is re-stamped with the successor's fence at revision 1.
+ rec := doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+ pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, testFenceR, pf.Incarnation)
+ assert.Equal(t, int64(1), pf.Revision)
+
+ // The stale incarnation cannot write into the successor.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 1, false, true), "runtime-0")
+ assert.Equal(t, http.StatusPreconditionFailed, rec.Code)
+}
+
+func TestPolicyPersistUnusableFilesFallBackToInput(t *testing.T) {
+ cases := []struct {
+ name string
+ data []byte
+ }{
+ {"corrupt", []byte("{corrupt json")},
+ {"newer schema", []byte(`{"v":99,"incarnation":"x","attachmentId":"y","revision":1,"policy":{}}` + "\n")},
+ {"unparseable policy", func() []byte {
+ raw, _ := policy.EncodePolicyFile(testFenceR, testFenceA, 5, json.RawMessage(`{"egress":"not-a-list"}`))
+ return raw
+ }()},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ f := h.fileFor(policyTestUID)
+ f.data = tc.data
+ f.exists = true
+
+ // Registration succeeds; the binding input seeds the subject.
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ rec := doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+
+ // The unusable file was quarantined, then replaced by the
+ // seeded record's own file.
+ assert.True(t, f.exists, "the seeded record persists its own file")
+ pf, _ := decodePolicyFile(t, f)
+ assert.Equal(t, int64(1), pf.Revision)
+ })
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Removal / rebind purge the durable record
+// ---------------------------------------------------------------------------
+
+func TestPolicyPersistRemovalPurgesRecord(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ require.True(t, h.fileFor(policyTestUID).exists, "precondition: the seeded record persisted")
+
+ // Binding removal: deny-first is also the durable state.
+ rec := doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, nil))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.False(t, h.fileFor(policyTestUID).exists, "the removal purges the persisted policy")
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ assert.Equal(t, http.StatusNotFound, rec.Code)
+
+ // A later registration starts from its own input — never the removed
+ // policy.
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 3, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ _, doc := mustPolicyRevision(t, rec)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+}
+
+func TestPolicyPersistRebindPurgesRecord(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ require.True(t, h.fileFor(policyTestUID).exists)
+
+ // Relay mutation at revision 2, then rebind.
+ rec := doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ const newRuntime = "runtime-2"
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, newRuntime, "attachment-2", 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, policyTestUID, newRuntime, "attachment-2", constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The previous instance's relayed policy is gone; the successor is
+ // seeded from its own binding input at revision 1.
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+ pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, newRuntime, pf.Incarnation, "the file is stamped with the successor's fence")
+}
+
+// ---------------------------------------------------------------------------
+// Commit protocol outcomes
+// ---------------------------------------------------------------------------
+
+func TestPolicyPersistCommitOutcomes(t *testing.T) {
+ t.Run("pre-rename failure nacks without latch", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ f := h.fileFor(policyTestUID)
+ f.saveState, f.saveErr = policy.FileUnchanged, errors.New("no space on temp create")
+
+ rec := doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusInternalServerError, rec.Code)
+
+ // Last-good kept on both sides; no restore, no latch.
+ assert.Equal(t, 0, f.restoreCalls)
+ assert.Equal(t, int64(1), mustReadRevision(t, h, policyTestUID))
+ f.saveErr, f.saveState = nil, policy.FileCommitted
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ assert.Equal(t, http.StatusOK, rec.Code, "the next write with a working store succeeds")
+ })
+
+ t.Run("uncertain persist latches recovery and restores", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ goodFile := append([]byte(nil), h.fileFor(policyTestUID).data...)
+
+ f := h.fileFor(policyTestUID)
+ f.saveState, f.saveErr = policy.FileUnknown, errors.New("rename returned EIO")
+ rec := doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusServiceUnavailable, rec.Code)
+
+ assert.Equal(t, 1, f.restoreCalls)
+ assert.Equal(t, string(goodFile), string(f.data), "the previous file image was restored")
+ assert.True(t, h.srv.policyRecoveryActive(), "the recovery latch freezes policy writes until restart")
+
+ // Frozen: relay writes 503, healthz 503, status flags recovery and
+ // drops readiness.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
+ rec = doRequest(t, h.srv, http.MethodGet, "/healthz", "")
+ assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
+ assert.Contains(t, rec.Body.String(), "policy persistence recovery required")
+ status := mustStatus(t, h.srv)
+ assert.True(t, status.PolicyRecovery)
+ assert.False(t, status.Ready)
+ })
+
+ t.Run("apply failure rolls the file back", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ goodFile := append([]byte(nil), h.fileFor(policyTestUID).data...)
+
+ // The nft apply fails on an active subject: the file is rolled back
+ // and the registry keeps the previous policy.
+ h.nft.policyErr = errors.New("nft busy")
+ rec := doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusInternalServerError, rec.Code)
+ h.nft.policyErr = nil
+
+ assert.Equal(t, 1, h.fileFor(policyTestUID).restoreCalls)
+ assert.Equal(t, string(goodFile), string(h.fileFor(policyTestUID).data))
+ assert.False(t, h.srv.policyRecoveryActive(), "a confirmed restore needs no latch")
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(h.srv, s, "api.example.com"), "the registry keeps the previous policy")
+ })
+}
+
+// mustReadRevision reads the recorded revision through the relay GET.
+func mustReadRevision(t *testing.T, h *policyPersistHarness, uid string) int64 {
+ t.Helper()
+ rec := doPolicy(t, h.srv, http.MethodGet, uid, "", "")
+ rev, _ := mustPolicyRevision(t, rec)
+ return rev
+}
+
+// ---------------------------------------------------------------------------
+// Capability + healthy posture
+// ---------------------------------------------------------------------------
+
+func TestPolicyPersistCapabilityFlag(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ status := mustStatus(t, h.srv)
+ assert.True(t, status.PolicyTransfer, "policy persistence configured: the Fastlet's transfer capability")
+
+ srv, _, _ := fastSandboxTestServer(t)
+ rec := doRequest(t, srv, http.MethodGet, constants.ActionsStatusPath, "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.NotContains(t, rec.Body.String(), "policyTransfer", "the capability stays omitted when false")
+ assert.NotContains(t, rec.Body.String(), "policyRecovery")
+}
diff --git a/components/egress/fastsandbox_policy_relay_test.go b/components/egress/fastsandbox_policy_relay_test.go
new file mode 100644
index 000000000..bc14e2c4f
--- /dev/null
+++ b/components/egress/fastsandbox_policy_relay_test.go
@@ -0,0 +1,327 @@
+// 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/json"
+ "net/http"
+ "net/http/httptest"
+ "strconv"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// ---------------------------------------------------------------------------
+// Relay policy surface: /policy/{sandboxUid}
+// ---------------------------------------------------------------------------
+
+const policyTestUID = "policy-u"
+
+// policyAllow is a minimal effective policy.
+func policyAllow() string {
+ return `{"defaultAction":"deny","egress":[{"action":"allow","target":"api.example.com"}]}`
+}
+
+func policyAllowAlt() string {
+ return `{"defaultAction":"deny","egress":[{"action":"allow","target":"other.example.com"}]}`
+}
+
+// policyPutDoc wraps a policy body in the relay document with an optional
+// precondition (either spelling).
+func policyPutDoc(policyBody string, revision int64, withRevision, withExpected bool) string {
+ var b strings.Builder
+ b.WriteString(`{"policy":`)
+ b.WriteString(policyBody)
+ if withRevision {
+ b.WriteString(`,"revision":`)
+ b.WriteString(strconv.FormatInt(revision, 10))
+ }
+ if withExpected {
+ b.WriteString(`,"expectedRevision":`)
+ b.WriteString(strconv.FormatInt(revision, 10))
+ }
+ b.WriteString(`}`)
+ return b.String()
+}
+
+// doPolicy drives one relay request against the surface; incarnation is the
+// optional expectedIncarnation precondition header.
+func doPolicy(t *testing.T, srv *fastSandboxPolicyServer, method, uid, body, incarnation string) *httptest.ResponseRecorder {
+ t.Helper()
+ req := httptest.NewRequest(method, constants.PolicyRelayPathPrefix+uid, strings.NewReader(body))
+ if incarnation != "" {
+ req.Header.Set(constants.EgressVaultIncarnationHeader, incarnation)
+ }
+ rec := httptest.NewRecorder()
+ srv.Handler().ServeHTTP(rec, req)
+ return rec
+}
+
+// mustPolicyRevision decodes a relay GET/PUT body's revision.
+func mustPolicyRevision(t *testing.T, rec *httptest.ResponseRecorder) (int64, policyRelayDocument) {
+ t.Helper()
+ require.Contains(t, []int{http.StatusOK, http.StatusCreated}, rec.Code, rec.Body.String())
+ var doc policyRelayDocument
+ require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &doc))
+ return doc.Revision, doc
+}
+
+func TestPolicyRelayUnknownSubject404NoCache(t *testing.T) {
+ srv, _, _ := fastSandboxTestServer(t)
+ for _, method := range []string{http.MethodGet, http.MethodPut, http.MethodDelete} {
+ rec := doPolicy(t, srv, method, "ghost", policyPutDoc(policyAllow(), 0, false, false), "")
+ assert.Equal(t, http.StatusNotFound, rec.Code, method)
+ }
+ // No policy record was materialized for the unknown subject.
+ srv.mu.Lock()
+ _, stored := srv.policies[subject.FromSandboxUID("ghost")]
+ srv.mu.Unlock()
+ assert.False(t, stored, "the relay surface never materializes state for an unregistered subject")
+}
+
+func TestPolicyRelayPutReplacesSeededRecord(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ // The binding input seeded the record at revision 1: GET serves the
+ // seeded policy even before any relay write.
+ rec := doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ require.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+
+ // PUT replaces at the successor revision.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 0, false, false), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rev, doc = mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(2), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+
+ // Enforcement followed the relay write.
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, subject.StateActive, mustState(reg.Get(s)))
+ assert.Equal(t, "allow", reg.UserPolicy(s).Evaluate("other.example.com"))
+
+ // GET echoes the recorded policy + revision.
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc = mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(2), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+}
+
+func TestPolicyRelayPreconditions(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ // The binding input seeded revision 1; the first relay PUT is a replace.
+ rec := doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Stale expectedRevision is a 412.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 1, false, true), "")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+
+ // The GET revision acts as the precondition (round trip).
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ rev, _ := mustPolicyRevision(t, rec)
+ require.Equal(t, int64(2), rev)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), rev, true, false), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rev, _ = mustPolicyRevision(t, rec)
+ require.Equal(t, int64(3), rev)
+
+ // Stale round-trip revision: 412.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), rev-1, true, false), "")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+
+ // Both spellings agreeing is accepted.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), rev, true, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Both spellings disagreeing is a 400.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, `{"policy":`+policyAllow()+`,"revision":1,"expectedRevision":2}`, "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+
+ // DELETE, then a conditional PUT against the missing record: 412, not a
+ // create.
+ rec = doPolicy(t, srv, http.MethodDelete, policyTestUID, "", "")
+ require.Equal(t, http.StatusNoContent, rec.Code)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 4, false, true), "")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+
+ // Unconditional PUT recreates from scratch at revision 1.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 0, false, false), "")
+ require.Equal(t, http.StatusCreated, rec.Code)
+ rev, _ = mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+}
+
+func TestPolicyRelayInvalidPolicyKeepsLastGood(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ rec := doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 0, false, false), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Invalid policy content is a 400 NACK; last-good kept. (defaultAction
+ // is not action-validated by the parser; egress rule actions are.)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(`{"defaultAction":"deny","egress":[{"action":"bogus","target":"x.com"}]}`, 0, false, false), "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, `{`, "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, `{"unknownField":1}`, "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, `{}`, "")
+ require.Equal(t, http.StatusBadRequest, rec.Code)
+
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg.UserPolicy(s).Evaluate("other.example.com"), "last-good policy untouched")
+}
+
+func TestPolicyRelayDeleteRevertsDenyFirst(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ s := setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+ require.Equal(t, subject.StateActive, mustState(reg.Get(s)))
+
+ // DELETE removes the seeded record and reverts the subject to deny-first
+ // — the binding policy goes with it (runtime truth is relay-owned).
+ rec := doPolicy(t, srv, http.MethodDelete, policyTestUID, "", "")
+ require.Equal(t, http.StatusNoContent, rec.Code)
+ assert.Equal(t, subject.StateDenying, mustState(reg.Get(s)))
+ assert.Nil(t, reg.UserPolicy(s))
+ assert.Nil(t, reg.EffectivePolicy(s))
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ assert.Equal(t, http.StatusNotFound, rec.Code)
+
+ // Duplicate DELETE is a 404.
+ rec = doPolicy(t, srv, http.MethodDelete, policyTestUID, "", "")
+ assert.Equal(t, http.StatusNotFound, rec.Code)
+
+ // A re-add via SET_BINDING + data-plane-ready reactivates.
+ rec = doAction(t, srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, srv, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.Equal(t, subject.StateActive, mustState(reg.Get(s)))
+}
+
+func TestPolicyRelayDenyingSubjectHoldsPending(t *testing.T) {
+ srv, _, _ := fastSandboxTestServer(t)
+
+ // SET_BINDING only: subject registered, still denying.
+ rec := doAction(t, srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // A relay PUT while denying replaces the pending policy (held to the
+ // data-plane-ready barrier) at the successor revision.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(2), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+
+ // GET serves the pending policy while held.
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ _, doc = mustPolicyRevision(t, rec)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+
+ // data-plane-ready activates the relayed policy.
+ rec = doAction(t, srv, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, srv, hookBody(t, policyTestUID, testFenceR, testFenceA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(srv, s, "other.example.com"))
+}
+
+// reg_UserEvaluate evaluates the subject's recorded user policy (test aid to
+// keep assertions readable).
+func reg_UserEvaluate(srv *fastSandboxPolicyServer, s subject.Subject, domain string) string {
+ pol := srv.reg.UserPolicy(s)
+ if pol == nil {
+ return "no-policy"
+ }
+ return pol.Evaluate(domain)
+}
+
+func TestPolicyRelayIncarnationPrecondition(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ rec := doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), testFenceR)
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 1, false, true), "runtime-999")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "runtime-999")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", testFenceR)
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ rec = doPolicy(t, srv, http.MethodDelete, policyTestUID, "", "runtime-999")
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+}
+
+func TestPolicyRelayMethodNotAllowed(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ rec := doPolicy(t, srv, http.MethodPost, policyTestUID, policyPutDoc(policyAllow(), 0, false, false), "")
+ require.Equal(t, http.StatusMethodNotAllowed, rec.Code)
+ assert.Contains(t, rec.Header().Get("Allow"), "PUT")
+
+ rec = doPolicy(t, srv, http.MethodPatch, policyTestUID, "{}", "")
+ require.Equal(t, http.StatusMethodNotAllowed, rec.Code)
+
+ // The bare /policy path redirects into the subtree; the old UID-header
+ // surface stays gone.
+ rec = doRequest(t, srv, http.MethodGet, "/policy", "")
+ assert.NotEqual(t, http.StatusOK, rec.Code)
+}
+
+func TestPolicyRelayRebindResetsRecord(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ s := setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+
+ rec := doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 0, false, false), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Rebind: same UID, NEW runtime instance — the recorded policy is gone.
+ const newRuntime = "runtime-2"
+ rec = doAction(t, srv, bindBody(t, policyTestUID, vaultTestIP, newRuntime, "attachment-2", 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, srv, hookBody(t, policyTestUID, newRuntime, "attachment-2", constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The relayed (previous instance's) policy is gone: GET serves the NEW
+ // binding input at revision 1 — the successor was reseeded.
+ rec = doPolicy(t, srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(1), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+ assert.NotContains(t, string(doc.Policy), "other.example.com", "the rebind discards the previous instance's recorded policy")
+ assert.Equal(t, "allow", reg_UserEvaluate(srv, s, "api.example.com"), "the new binding input seeds the successor")
+
+ // The old incarnation cannot write into the successor.
+ rec = doPolicy(t, srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 1, false, true), testFenceR)
+ require.Equal(t, http.StatusPreconditionFailed, rec.Code)
+}
diff --git a/components/egress/fastsandbox_policy_snapshot.go b/components/egress/fastsandbox_policy_snapshot.go
new file mode 100644
index 000000000..cf2ea9ae6
--- /dev/null
+++ b/components/egress/fastsandbox_policy_snapshot.go
@@ -0,0 +1,359 @@
+// 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.
+
+// Policy snapshot transfer across pause/resume, mirroring the vault snapshot
+// transfer (fastsandbox_vault_snapshot.go). POLICY_EXPORT copies the
+// subject's recorded policy file into the snapshot bundle strictly before the
+// runtime teardown and seals the subject; POLICY_IMPORT lands the bundle
+// file re-stamped with the restored fence — the only authorized incarnation
+// transfer — through the same commit protocol as the relay writes, marking
+// the record file-backed so later binding replays never override it. The
+// invocation side (driver/Fastlet hooks, snapshot manifest) is platform
+// work in the fast-sandbox repository.
+package main
+
+import (
+ "bytes"
+ "errors"
+ "fmt"
+ "io"
+ "io/fs"
+ "net/http"
+ "os"
+ "strings"
+
+ "github.com/alibaba/opensandbox/egress/pkg/actionhandler"
+ "github.com/alibaba/opensandbox/egress/pkg/log"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// maxPolicySnapshotBytes bounds a bundle read: the largest valid policy file
+// is a max relay body plus the encoded envelope — anything over this is not
+// a v1 policy file.
+const maxPolicySnapshotBytes = policy.MaxEncodedPolicyFileBytes
+
+var errPolicySnapshotTooLarge = fmt.Errorf("policy bundle file exceeds %d bytes", maxPolicySnapshotBytes)
+
+// applyPolicyExport copies the subject's recorded policy file into the bundle
+// target and marks the subject sealed. A subject without a policy file just
+// seals. Any failure leaves the subject unsealed and its enforcement
+// unchanged; what the pause flow does with that is the caller's call — the
+// fast-sandbox driver fails the pause checkpoint, so the teardown never runs
+// without a bundle. A retried export re-copies idempotently (while sealed no
+// relay op can change the source).
+//
+// Three phases: guards + a consistent source image under s.mu, the
+// driver-owned copy without the lock (it may be slow; every action and relay
+// op goes through s.mu), then a re-check under the lock — sealed only if the
+// source is still the exact copied image, else 409. The recovery latch
+// rejects the export in both guarded phases: with on-disk state unconfirmed,
+// the copy plus the teardown purge would make uncertain bytes the only
+// surviving recorded policy.
+func (s *fastSandboxPolicyServer) applyPolicyExport(env *actionhandler.Envelope) (int, error) {
+ if s.policyFiles == nil {
+ return http.StatusInternalServerError, errors.New("policy export requires policy persistence (OPENSANDBOX_EGRESS_POLICY_DIR)")
+ }
+ subj := subject.FromSandboxUID(env.Sandbox.UID)
+ fence := subject.FromRevision(env)
+ target := strings.TrimSpace(env.Snapshot.Path)
+ if s.policyFiles.reservesPath(target) {
+ return http.StatusBadRequest, fmt.Errorf("policy bundle target %q must not live under the policy persistence directory", target)
+ }
+ // A subject that never registered (a sandbox created without an egress
+ // binding, or after terminal cleanup) has no policy to carry: 200 so the
+ // checkpoint proceeds — a 404 would fail every pause of a binding-less
+ // sandbox. A registered subject under a stale fence still fails below.
+ if _, ok := s.reg.Fence(subj); !ok {
+ log.Infof("policy export: subject %s not registered; no policy to carry, checkpoint proceeds without it", subj)
+ return http.StatusOK, nil
+ }
+
+ // Phase 1: guards + consistent source image.
+ s.mu.Lock()
+ snap, status, err := s.policyExportSourceImageLocked(subj, fence)
+ if err != nil {
+ s.mu.Unlock()
+ return status, err
+ }
+ s.mu.Unlock()
+
+ // Phase 2: no lock held across the driver-owned write.
+ if snap.Exists() {
+ bundle, err := s.policyFiles.newFile(target)
+ if err != nil {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle target unavailable: %w", err)
+ }
+ state, err := bundle.SaveRaw(snap.Data())
+ if err != nil || state != policy.FileCommitted {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle copy failed (state %v): %v", state, err)
+ }
+ }
+
+ // Phase 3: seal only against the exact copied image.
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ live, status, err := s.policyExportSourceImageLocked(subj, fence)
+ if err != nil {
+ return status, err
+ }
+ if live.Exists() != snap.Exists() || (snap.Exists() && !bytes.Equal(live.Data(), snap.Data())) {
+ return http.StatusConflict, fmt.Errorf("policy file changed during export for subject %s; bundle copy not sealed", subj)
+ }
+ if !snap.Exists() {
+ // Nothing to carry: a previous attempt may have left stale bytes at
+ // the target — remove them, or a later import would restore a policy
+ // deleted during the pause.
+ bundle, err := s.policyFiles.newFile(target)
+ if err != nil {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle target unavailable: %w", err)
+ }
+ state, err := bundle.Delete()
+ if err != nil || (state != policy.FileCommitted && state != policy.FileUnchanged) {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle removal failed (state %v): %v", state, err)
+ }
+ }
+ // Durable seal first: a restart before REMOVE_BINDING must reload the
+ // entry sealed, or relay writes would stale the taken bundle.
+ if err := s.policyFiles.seal(subj); err != nil {
+ return http.StatusInternalServerError, fmt.Errorf("policy seal marker: %w", err)
+ }
+ e := s.policies[subj]
+ if e == nil || e.fence != fence {
+ e = &policyEntry{fence: fence}
+ }
+ e.sealed = true
+ s.policies[subj] = e
+ if snap.Exists() {
+ log.Infof("subject %s: policy exported to snapshot bundle, subject sealed", subj)
+ } else {
+ log.Infof("subject %s: no policy file to export, subject sealed", subj)
+ }
+ return http.StatusOK, nil
+}
+
+// policyExportSourceImageLocked runs the export guards and returns a
+// consistent image of the subject's policy file. Callers hold s.mu.
+func (s *fastSandboxPolicyServer) policyExportSourceImageLocked(subj subject.Subject, fence subject.Fencing) (*policy.PolicyFileSnapshot, int, error) {
+ regFence, ok := s.reg.Fence(subj)
+ if !ok {
+ return nil, http.StatusNotFound, fmt.Errorf("policy export for unknown subject %s", subj)
+ }
+ if !regFence.Matches(fence) {
+ return nil, http.StatusConflict, fmt.Errorf("stale policy export (fence mismatch) for subject %s", subj)
+ }
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ return nil, http.StatusServiceUnavailable, fmt.Errorf("policy persistence recovery required: %s", recovery.reason)
+ }
+ fs, err := s.policyFiles.storeFor(subj)
+ if err != nil {
+ return nil, http.StatusInternalServerError, fmt.Errorf("policy file store unavailable: %w", err)
+ }
+ snap, err := fs.Snapshot()
+ if err != nil {
+ return nil, http.StatusInternalServerError, fmt.Errorf("policy file snapshot: %w", err)
+ }
+ if snap.Exists() {
+ // Carry only bytes attributable to the registered fence: a leftover
+ // from a previous incarnation (purge failed), a corrupt file, or a
+ // newer schema is treated as absent — never exported, or import
+ // would re-stamp a foreign policy as current.
+ pf, _, decErr := policy.DecodePolicyFile(snap.Data())
+ if decErr != nil || pf.Incarnation != regFence.RuntimeInstanceID || pf.AttachmentID != regFence.AttachmentID {
+ what := "unattributable fence"
+ if errors.Is(decErr, policy.ErrUnsupportedPolicyFileVersion) {
+ what = "newer schema"
+ } else if decErr != nil {
+ what = "unreadable"
+ }
+ log.Infof("subject %s: policy file not carried (%s)", subj, what)
+ return policy.NewFileSnapshot("", nil, false), 0, nil
+ }
+ }
+ return snap, 0, nil
+}
+
+// applyPolicyImport lands the bundle file as the subject's policy file,
+// re-stamped with the restored fence from the envelope (restore may land on
+// any Pod, so the recorded incarnation is replaced, not compared). The file
+// goes through the commit protocol and the record materializes file-backed;
+// the policy activates at the same data-plane-ready barrier as the vault.
+//
+// The bundle is read, decoded, and parsed before the commit serialization.
+// Delivery is at-least-once: a local revision newer than the bundle acks
+// idempotently — relay writes after the first import are never rolled back.
+// Unregistered (before SET_BINDING), only the file lands and the
+// registration-time reload validates it; registered under the envelope
+// fence, the policy installs into the live record and a rejected bundle is
+// a 400 with last-good kept.
+func (s *fastSandboxPolicyServer) applyPolicyImport(env *actionhandler.Envelope) (int, error) {
+ if s.policyFiles == nil {
+ return http.StatusInternalServerError, errors.New("policy import requires policy persistence (OPENSANDBOX_EGRESS_POLICY_DIR)")
+ }
+ subj := subject.FromSandboxUID(env.Sandbox.UID)
+ fence := subject.FromRevision(env)
+ source := strings.TrimSpace(env.Snapshot.Path)
+ if s.policyFiles.reservesPath(source) {
+ return http.StatusBadRequest, fmt.Errorf("policy bundle source %q must not live under the policy persistence directory", source)
+ }
+
+ // Read before locking; a missing/oversized/unreadable source is
+ // permanent — the fastlet retry cannot repair it.
+ data, err := readPolicyBundle(source)
+ if errors.Is(err, fs.ErrNotExist) {
+ return http.StatusNotFound, fmt.Errorf("policy bundle file %q does not exist", source)
+ }
+ if errors.Is(err, errPolicySnapshotTooLarge) {
+ return http.StatusBadRequest, err
+ }
+ if err != nil {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle read failed: %w", err)
+ }
+ pf, body, err := policy.DecodePolicyFile(data)
+ if err != nil {
+ return http.StatusBadRequest, fmt.Errorf("invalid policy bundle file: %v", err)
+ }
+ pol, parseErr := policy.ParsePolicy(string(body))
+ if parseErr != nil {
+ return http.StatusBadRequest, fmt.Errorf("invalid policy bundle content: %v", parseErr)
+ }
+ // The authorized incarnation transfer.
+ payload, err := policy.EncodePolicyFile(fence.RuntimeInstanceID, fence.AttachmentID, pf.Revision, body)
+ if err != nil {
+ return http.StatusInternalServerError, fmt.Errorf("policy bundle re-stamp failed: %w", err)
+ }
+
+ // Serialize the commit against relay writes; guards run under s.mu
+ // inside (the ordering policyCommitMu → s.mu is the commit path's).
+ s.policyCommitMu.Lock()
+ defer s.policyCommitMu.Unlock()
+
+ s.mu.Lock()
+ // The latch freezes every policy file mutation; only a restart
+ // reconciles (relay-write parity).
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ s.mu.Unlock()
+ return http.StatusServiceUnavailable, fmt.Errorf("policy persistence recovery required: %s", recovery.reason)
+ }
+ // At-least-once delivery: never roll a newer local revision back. The
+ // guard requires the stored fence to match the envelope — a newer file
+ // under an old incarnation is stale local state the import must
+ // supersede, not ack.
+ if fs, fsErr := s.policyFiles.storeFor(subj); fsErr == nil {
+ if cur, snapErr := fs.Snapshot(); snapErr == nil && cur.Exists() {
+ if curPF, _, decErr := policy.DecodePolicyFile(cur.Data()); decErr == nil &&
+ curPF.Incarnation == fence.RuntimeInstanceID && curPF.AttachmentID == fence.AttachmentID &&
+ curPF.Revision > pf.Revision {
+ s.mu.Unlock()
+ log.Infof("subject %s: policy import superseded (local revision %d > bundle revision %d), idempotent ack", subj, curPF.Revision, pf.Revision)
+ return http.StatusOK, nil
+ }
+ }
+ }
+ regFence, registered := s.reg.Fence(subj)
+ if registered && !regFence.Matches(fence) {
+ s.mu.Unlock()
+ return http.StatusConflict, fmt.Errorf("stale policy import (fence mismatch) for subject %s", subj)
+ }
+ state, _ := s.reg.Get(subj)
+ stateActive := state == subject.StateActive
+ sealed := false
+ if e := s.policies[subj]; e != nil && e.sealed {
+ sealed = true
+ }
+ s.mu.Unlock()
+
+ err = s.persistPolicyCandidateLocked(
+ subj,
+ func(fs vaultFileStore) (policy.FileMutationState, error) {
+ return fs.SaveRaw(payload)
+ },
+ func() error {
+ if !registered {
+ // Before SET_BINDING: registration reloads and validates.
+ s.mu.Lock()
+ delete(s.policies, subj)
+ s.mu.Unlock()
+ return s.policyFiles.unseal(subj)
+ }
+ return s.installImportedPolicyLocked(subj, fence, pf.Revision, pol, stateActive, sealed)
+ },
+ )
+ if err != nil {
+ log.Errorf("subject %s: policy import failed: %v", subj, err)
+ status := http.StatusInternalServerError
+ if recovery := s.policyRecovery.Load(); recovery != nil {
+ status = http.StatusServiceUnavailable
+ }
+ return status, errors.New("policy import persistence failure")
+ }
+ if registered {
+ log.Infof("subject %s: policy imported from snapshot bundle (revision %d, re-stamped to %s/%s)",
+ subj, pf.Revision, fence.RuntimeInstanceID, fence.AttachmentID)
+ } else {
+ log.Infof("subject %s: policy bundle landed for the next registration (revision %d, re-stamped to %s/%s)",
+ subj, pf.Revision, fence.RuntimeInstanceID, fence.AttachmentID)
+ }
+ return http.StatusOK, nil
+}
+
+// installImportedPolicyLocked binds the imported revision into the live
+// per-subject record under the restored fence, replacing any stale record,
+// and unseals it. The record is only replaced once enforcement (or the
+// pending store) accepted — a failure leaves the live state untouched while
+// the commit protocol rolls the file back. Enforcement runs WITHOUT s.mu
+// (it takes the registry write lock); the s.mu suffix is the docstring's
+// "Locked" sense: map mutations under s.mu, unseal after acceptance.
+func (s *fastSandboxPolicyServer) installImportedPolicyLocked(subj subject.Subject, fence subject.Fencing, revision int64, pol *policy.NetworkPolicy, stateActive, wasSealed bool) error {
+ if stateActive {
+ // Enforcement first: a failed apply leaves the record untouched
+ // (the commit protocol rolls the file back and keeps the seal).
+ if err := s.applyPolicy(subj, pol); err != nil {
+ return err
+ }
+ }
+ s.mu.Lock()
+ if !stateActive {
+ s.pendingPolicies[subj] = pol
+ }
+ s.policies[subj] = &policyEntry{revision: revision, fence: fence, hydrated: true}
+ s.mu.Unlock()
+ // Unseal only after the state accepted — a failed apply rolls the file
+ // back and keeps the seal.
+ if wasSealed {
+ if err := s.policyFiles.unseal(subj); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// readPolicyBundle reads the driver-staged bundle source with a hard size
+// cap — a read-only lookup in the driver's trust domain, so plain bounded
+// I/O suffices (writes keep the hardened atomic machinery).
+func readPolicyBundle(path string) ([]byte, error) {
+ f, err := os.Open(path)
+ if err != nil {
+ return nil, err
+ }
+ defer f.Close()
+ data, err := io.ReadAll(io.LimitReader(f, maxPolicySnapshotBytes+1))
+ if err != nil {
+ return nil, err
+ }
+ if len(data) > maxPolicySnapshotBytes {
+ return nil, errPolicySnapshotTooLarge
+ }
+ return data, nil
+}
diff --git a/components/egress/fastsandbox_policy_snapshot_test.go b/components/egress/fastsandbox_policy_snapshot_test.go
new file mode 100644
index 000000000..21a938bd2
--- /dev/null
+++ b/components/egress/fastsandbox_policy_snapshot_test.go
@@ -0,0 +1,431 @@
+// 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/json"
+
+ "net/http"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/alibaba/opensandbox/egress/pkg/constants"
+ "github.com/alibaba/opensandbox/egress/pkg/policy"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+// Policy snapshot transfer across pause/resume. The driver side is platform
+// work — these tests drive the egress hooks via the actions protocol. The
+// shared snapshot fence constants (snapshotResumeR/A) live in the vault
+// snapshot tests.
+
+// ---------------------------------------------------------------------------
+// Export: copy + seal
+// ---------------------------------------------------------------------------
+
+func TestPolicySnapshotExportCopiesAndSeals(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The bundle copy is byte-identical to the subject's policy file.
+ bundle := h.fakeForPath(bundlePath)
+ policyFile := h.fileFor(policyTestUID)
+ require.True(t, bundle.exists, "export must publish the bundle file")
+ require.True(t, policyFile.exists)
+ assert.Equal(t, policyFile.data, bundle.data)
+
+ // Sealed: every relay op is a 409 — the bundle copy is already taken.
+ for _, method := range []string{http.MethodGet, http.MethodPut, http.MethodDelete} {
+ rec := doPolicy(t, h.srv, method, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ assert.Equal(t, http.StatusConflict, rec.Code, method)
+ }
+ // Policy enforcement is unchanged while the sandbox is paused.
+ state, ok := h.reg.Get(subject.FromSandboxUID(policyTestUID))
+ require.True(t, ok)
+ assert.Equal(t, subject.StateActive, state)
+
+ // A retried export (lost ack) re-copies and re-seals idempotently.
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.Equal(t, policyFile.data, h.fakeForPath(bundlePath).data)
+}
+
+func TestPolicySnapshotExportWithoutPolicyFileStillSeals(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+
+ // A registered subject with NO recorded policy (binding removed): the
+ // removal purged the file, so the export carries nothing but still seals.
+ rec := doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, nil))
+ require.Equal(t, http.StatusOK, rec.Code)
+ require.False(t, h.fileFor(policyTestUID).exists, "precondition: the removal purged the file")
+
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.False(t, h.fakeForPath(bundlePath).exists, "nothing to carry: no policy file, no bundle write")
+}
+
+// An unregistered subject has no policy to carry: the export is a 200 no-op.
+func TestPolicySnapshotExportUnregisteredSubjectIsNoOp(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", "unregistered.json")
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, "unregistered-sandbox", testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.False(t, h.fakeForPath(bundlePath).exists, "nothing to carry: no subject, no bundle write")
+}
+
+func TestPolicySnapshotExportGuards(t *testing.T) {
+ t.Run("persistence disabled", func(t *testing.T) {
+ srv, reg, _ := fastSandboxTestServer(t)
+ setBindingAndReady(t, srv, reg, policyTestUID, vaultTestIP, strPtr(policyAllow()))
+ rec := doAction(t, srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", "/tmp/bundle.json"))
+ assert.Equal(t, http.StatusInternalServerError, rec.Code)
+ rec = doAction(t, srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_IMPORT", "/tmp/bundle.json"))
+ assert.Equal(t, http.StatusInternalServerError, rec.Code)
+ })
+ t.Run("stale fence", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, "old-runtime", testFenceA, "POLICY_EXPORT", "/tmp/bundle.json"))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed)
+ })
+ t.Run("recovery latch rejects the export", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ h.srv.requirePolicyRecoveryLocked("simulated latch")
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed)
+ assert.False(t, h.fakeForPath(bundlePath).exists, "no bundle copy while the latch holds")
+ })
+ t.Run("target under the policy persistence directory", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ inside := filepath.Join(h.dir, "other.json") // another subject's file
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", inside))
+ assert.Equal(t, http.StatusBadRequest, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed)
+ })
+ t.Run("concurrent relay write abandons the seal", func(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ copied := h.fileFor(policyTestUID).data
+
+ // A relay write lands mid-copy: the copy is stale, phase 3 refuses
+ // to seal.
+ newer, err := policy.EncodePolicyFile(testFenceR, testFenceA, 2, json.RawMessage(policyAllowAlt()))
+ require.NoError(t, err)
+ bundle := h.fakeForPath(bundlePath)
+ bundle.onSave = func() {
+ f := h.fileFor(policyTestUID)
+ f.data = newer
+ f.exists = true
+ }
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed)
+ assert.Equal(t, copied, bundle.data, "the stale copy exists but is not sealed — the driver retries against the newer state")
+ })
+}
+
+// ---------------------------------------------------------------------------
+// Import: re-stamp + commit protocol
+// ---------------------------------------------------------------------------
+
+func TestPolicySnapshotImportLandsFileBeforeRegistration(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ oldBytes := h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+
+ // Resume on a fresh Pod: no subject registered yet; the driver imports
+ // before SET_BINDING.
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Landed via the commit protocol, re-stamped with the restored fence —
+ // the only authorized incarnation transfer.
+ pf, body := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, 1, pf.Version)
+ assert.Equal(t, snapshotResumeR, pf.Incarnation)
+ assert.Equal(t, snapshotResumeA, pf.AttachmentID)
+ assert.Equal(t, int64(5), pf.Revision)
+ assert.Contains(t, string(body), "other.example.com")
+ carried, err := os.ReadFile(bundlePath)
+ require.NoError(t, err)
+ assert.Equal(t, oldBytes, carried, "the bundle source is read, never consumed")
+
+ // No memory record before registration (the reload happens at
+ // SET_BINDING, fenced by the same identity).
+ h.srv.mu.Lock()
+ _, live := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, live)
+
+ // At registration the file reloads under the restored fence and
+ // supersedes the binding input; data-plane-ready activates it.
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, snapshotResumeR, snapshotResumeA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(5), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+ rec = doAction(t, h.srv, hookBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ s := subject.FromSandboxUID(policyTestUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(h.srv, s, "other.example.com"))
+ assert.Equal(t, "deny", reg_UserEvaluate(h.srv, s, "api.example.com"), "the bundle policy, not the bootstrap input, is enforced")
+}
+
+func TestPolicySnapshotImportAfterSetBindingInstallsAndUnseals(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+
+ // Export seals the subject (simulated pause), then resume on the same
+ // fence: the import lands, installs, and unseals.
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ require.True(t, e.sealed)
+ h.srv.mu.Unlock()
+
+ // The bundle carries revision 1 (seeded state) — rewrite it to revision
+ // 5 to prove the import wins over the live revision 1.
+ h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_IMPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The imported policy is live and unsealed.
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(5), rev)
+ assert.Contains(t, string(doc.Policy), "other.example.com")
+ h.srv.mu.Lock()
+ e = h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed, "the import unseals the subject")
+
+ // A relay write on top lands the successor revision.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 5, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, int64(6), pf.Revision)
+}
+
+func TestPolicySnapshotImportRejects(t *testing.T) {
+ newHarness := func(t *testing.T) (*policyPersistHarness, string) {
+ h := newPolicyPersistHarness(t)
+ return h, filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ }
+ t.Run("missing bundle file", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusNotFound, rec.Code)
+ })
+ t.Run("corrupt bundle", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ require.NoError(t, os.MkdirAll(filepath.Dir(bundlePath), 0o700))
+ require.NoError(t, os.WriteFile(bundlePath, []byte(`{"v":1,`), 0o600))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusBadRequest, rec.Code)
+ })
+ t.Run("invalid policy content", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ raw, err := policy.EncodePolicyFile(testFenceR, testFenceA, 5, json.RawMessage(`{"egress":"not-a-list"}`))
+ require.NoError(t, err)
+ require.NoError(t, os.MkdirAll(filepath.Dir(bundlePath), 0o700))
+ require.NoError(t, os.WriteFile(bundlePath, raw, 0o600))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusBadRequest, rec.Code)
+ })
+ t.Run("oversized bundle", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ require.NoError(t, os.MkdirAll(filepath.Dir(bundlePath), 0o700))
+ require.NoError(t, os.WriteFile(bundlePath, make([]byte, maxPolicySnapshotBytes+1), 0o600))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusBadRequest, rec.Code)
+ })
+ t.Run("source under the policy persistence directory", func(t *testing.T) {
+ h, _ := newHarness(t)
+ inside := filepath.Join(h.dir, "staged.json")
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", inside))
+ assert.Equal(t, http.StatusBadRequest, rec.Code)
+ })
+ t.Run("stale fence while registered", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ })
+ t.Run("recovery latch rejects the import", func(t *testing.T) {
+ h, bundlePath := newHarness(t)
+ h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+ h.srv.requirePolicyRecoveryLocked("simulated latch")
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
+ assert.False(t, h.fileFor(policyTestUID).exists, "no policy file mutation while latched")
+ })
+}
+
+func TestPolicySnapshotDuplicateImportDoesNotRollBack(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ h.seedPolicyBundle(t, bundlePath, 5, policyAllowAlt())
+
+ // First import lands revision 5 (registered, denying).
+ rec := doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, snapshotResumeR, snapshotResumeA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Relay writes resume: revision 6 lands.
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllow(), 5, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // A lost-ack retry must not roll revision 6 back to the bundle's 5.
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, int64(6), pf.Revision, "the newer relay write survives the retried import")
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(6), rev)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+}
+
+// TestPolicySnapshotRemoveBindingPurgesSealed: terminal cleanup removes the
+// record and the seal marker; the bundle copy survives (export strictly
+// precedes the teardown).
+func TestPolicySnapshotRemoveBindingPurgesSealed(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ require.True(t, h.fakeForPath(bundlePath).exists, "precondition: the bundle copy is intact")
+
+ rec = doAction(t, h.srv, removeBody(t, policyTestUID, testFenceR, testFenceA))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ h.srv.mu.Lock()
+ _, live := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
+ h.srv.mu.Unlock()
+ assert.False(t, live, "REMOVE_BINDING purges the record")
+ assert.False(t, h.fileFor(policyTestUID).exists, "REMOVE_BINDING purges the policy file")
+ assert.True(t, h.fakeForPath(bundlePath).exists, "the bundle copy is untouched by the teardown")
+
+ // The seal marker is gone with the purge.
+ subj := subject.FromSandboxUID(policyTestUID)
+ marker, err := h.pp.markerFor(subj)
+ require.NoError(t, err)
+ _, statErr := os.Stat(marker)
+ assert.True(t, os.IsNotExist(statErr), "the purge removes the seal marker")
+
+ // A later registration comes back unsealed from its own input.
+ rec = doAction(t, h.srv, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ h.srv.mu.Lock()
+ e := h.srv.policies[subj]
+ h.srv.mu.Unlock()
+ assert.False(t, e.sealed)
+ rec = doPolicy(t, h.srv, http.MethodGet, policyTestUID, "", "")
+ _, doc := mustPolicyRevision(t, rec)
+ assert.Contains(t, string(doc.Policy), "api.example.com")
+}
+
+// TestPolicySnapshotSealSurvivesRestart: a handler restart between export
+// and REMOVE_BINDING restores the sealed record from the durable marker.
+func TestPolicySnapshotSealSurvivesRestart(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Fresh server over the same persistence state + binding replay.
+ srv2, _, _ := fastSandboxTestServer(t)
+ pp2, err := newPolicyPersistence(h.dir)
+ require.NoError(t, err)
+ pp2.newFile = h.pp.newFile
+ srv2.SetPolicyFiles(pp2)
+ subj := subject.FromSandboxUID(policyTestUID)
+
+ rec = doAction(t, srv2, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 1, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ srv2.mu.Lock()
+ e := srv2.policies[subj]
+ srv2.mu.Unlock()
+ require.True(t, e.sealed, "binding replay restores the seal from the marker")
+ // The recorded policy reloads from the file (relay GET is 409 while
+ // sealed, so the file is the observable).
+ pf, body := decodePolicyFile(t, h.fileFor(policyTestUID))
+ assert.Equal(t, int64(1), pf.Revision)
+ assert.Contains(t, string(body), "api.example.com")
+
+ // Relay ops stay 409 while sealed; REMOVE_BINDING purges everything.
+ rec = doPolicy(t, srv2, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ assert.Equal(t, http.StatusConflict, rec.Code)
+
+ rec = doAction(t, srv2, removeBody(t, policyTestUID, testFenceR, testFenceA))
+ require.Equal(t, http.StatusOK, rec.Code)
+ marker, err := pp2.markerFor(subj)
+ require.NoError(t, err)
+ _, statErr := os.Stat(marker)
+ assert.True(t, os.IsNotExist(statErr), "the purge removes the seal marker")
+
+ rec = doAction(t, srv2, bindBody(t, policyTestUID, vaultTestIP, testFenceR, testFenceA, 2, strPtr(policyAllow())))
+ require.Equal(t, http.StatusOK, rec.Code)
+ srv2.mu.Lock()
+ e = srv2.policies[subj]
+ srv2.mu.Unlock()
+ assert.False(t, e.sealed)
+}
diff --git a/components/egress/fastsandbox_server.go b/components/egress/fastsandbox_server.go
index 14a88e327..24a2e002c 100644
--- a/components/egress/fastsandbox_server.go
+++ b/components/egress/fastsandbox_server.go
@@ -78,6 +78,26 @@ type fastSandboxPolicyServer struct {
// lock-free so healthz never contends).
vaultRecovery atomic.Pointer[vaultRecoveryState]
+ // policies tracks the recorded policy of each subject: the revision the
+ // relay preconditions fence on, the runtime fence the state was
+ // materialized under, and whether the policy is file-backed (loaded from
+ // the persisted file — the binding input no longer drives it). The
+ // policy itself lives in the registry (active subjects) or
+ // pendingPolicies (denying subjects); this entry carries only the
+ // bookkeeping the vault entry carries for vault state.
+ policies map[subject.Subject]*policyEntry
+ // policyFiles owns the per-subject policy files; nil keeps the policy
+ // memory-only (the default).
+ policyFiles *policyPersistence
+ // policyRecovery is the policy persistence recovery latch (same
+ // mechanics as vaultRecovery).
+ policyRecovery atomic.Pointer[policyRecoveryState]
+ // policyCommitMu serializes policy file-commit operations process-wide:
+ // the Fastlet serializes same-UID actions, but relayed writers from
+ // server replicas do not serialize with each other or with a concurrent
+ // SET_BINDING commit.
+ policyCommitMu sync.Mutex
+
// gatewayDNSRefs maps each subject to its gateway so the shared
// prerouting REDIRECT (sandbox DNS -> loopback proxy) is installed once
// per gateway and removed when the last subject using it is gone. Keyed
@@ -114,6 +134,7 @@ func newFastSandboxPolicyServer(ctx context.Context, reg *subject.MemoryRegistry
nft: nft,
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),
gatewayDNSRefs: make(map[subject.Subject]netip.Addr),
dnsRedirectInstall: iptables.SetupGatewayDNSRedirect,
@@ -226,13 +247,15 @@ func (s *fastSandboxPolicyServer) releaseGatewayDNSRedirect(subj subject.Subject
// Handler returns the fast-sandbox-profile HTTP mux: the Sandbox Actions Handler
// endpoints (Fastlet, envelope-driven) plus the healthz probe. Policy rides the
-// SET_BINDING binding input; the credential vault is egress-held behind the
+// SET_BINDING binding input at create and the relay surface (/policy/
+// {sandboxUid}) at runtime; the credential vault is egress-held behind the
// FastPath handler-relay (OSEP-0022) — there is 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)
mux.HandleFunc("/healthz", s.handleHealthz)
return mux
}
@@ -253,6 +276,9 @@ type healthzResponse struct {
// VaultHealthIssue is the non-empty vault-persistence reason (recovery
// latch; see fastsandbox_vault_persist.go). Status mirrors its class.
VaultHealthIssue string `json:"vaultHealthIssue,omitempty"`
+ // PolicyHealthIssue is the non-empty policy-persistence reason (recovery
+ // latch; see fastsandbox_policy_persist.go).
+ PolicyHealthIssue string `json:"policyHealthIssue,omitempty"`
}
// handleHealthz: 503 while the mitm stack is not ready (pre-create probe) and
@@ -277,6 +303,13 @@ func (s *fastSandboxPolicyServer) handleHealthz(w http.ResponseWriter, _ *http.R
})
return
}
+ if issue := s.policyHealthIssue(); issue != "" {
+ writeJSON(w, http.StatusServiceUnavailable, healthzResponse{
+ Status: "policy-unhealthy",
+ PolicyHealthIssue: issue,
+ })
+ return
+ }
if s.mitmGate.MitmPending() {
writeJSON(w, http.StatusServiceUnavailable, healthzResponse{Status: "mitmproxy-not-ready"})
return
@@ -294,6 +327,13 @@ func (s *fastSandboxPolicyServer) handleHealthz(w http.ResponseWriter, _ *http.R
})
return
}
+ if issue := s.policyHealthIssue(); issue != "" {
+ writeJSON(w, http.StatusServiceUnavailable, healthzResponse{
+ Status: "policy-unhealthy",
+ PolicyHealthIssue: issue,
+ })
+ return
+ }
writeJSON(w, http.StatusOK, healthzResponse{Status: "ok"})
}
@@ -502,14 +542,17 @@ func (s *fastSandboxPolicyServer) takeoverStaleSubject(stale subject.Subject) er
}
// dropSubjectState removes every piece of per-subject bookkeeping (vault,
-// pending policy, attachment) plus the persisted vault file — terminal
-// cleanup (OSEP-0022: REMOVE_BINDING purges memory + file).
+// policy record, pending policy, attachment) plus the persisted vault and
+// policy files — terminal cleanup (OSEP-0022: REMOVE_BINDING purges memory +
+// file).
func (s *fastSandboxPolicyServer) dropSubjectState(subj subject.Subject) {
s.mu.Lock()
delete(s.vaults, subj)
+ delete(s.policies, subj)
delete(s.pendingPolicies, subj)
delete(s.subjAtt, subj)
s.purgeVaultFile(subj)
+ s.purgePolicyFile(subj)
s.mu.Unlock()
}
diff --git a/components/egress/fastsandbox_server_test.go b/components/egress/fastsandbox_server_test.go
index 5760ab8c7..cb9eea015 100644
--- a/components/egress/fastsandbox_server_test.go
+++ b/components/egress/fastsandbox_server_test.go
@@ -672,25 +672,28 @@ func TestActionsInvalidEnvelopesRejected(t *testing.T) {
// ---------------------------------------------------------------------------
// TestFastSandboxServerSupersededRoutesGone: the UID-header-routed /policy and
-// /credential-vault surfaces are removed — policy rides only the SET_BINDING
-// binding input and the vault moves to the relay-only /vault/{sandboxUid}
-// surface, so the mux must not serve the old routes.
+// /credential-vault surfaces are removed — policy rides the SET_BINDING
+// binding input at create and the relay surface /policy/{sandboxUid} at
+// runtime, and the vault moves to the relay-only /vault/{sandboxUid} surface.
+// The bare /policy path redirects into the relay subtree; /credential-vault
+// must stay gone.
func TestFastSandboxServerSupersededRoutesGone(t *testing.T) {
srv, _, _ := fastSandboxTestServer(t)
for _, tc := range []struct {
method, path string
+ want int
}{
- {http.MethodGet, "/policy"},
- {http.MethodPut, "/policy"},
- {http.MethodPost, "/policy"},
- {http.MethodDelete, "/policy"},
- {http.MethodGet, "/credential-vault"},
- {http.MethodPost, "/credential-vault"},
- {http.MethodPatch, "/credential-vault"},
- {http.MethodDelete, "/credential-vault"},
+ {http.MethodGet, "/policy", http.StatusTemporaryRedirect},
+ {http.MethodPut, "/policy", http.StatusTemporaryRedirect},
+ {http.MethodPost, "/policy", http.StatusTemporaryRedirect},
+ {http.MethodDelete, "/policy", http.StatusTemporaryRedirect},
+ {http.MethodGet, "/credential-vault", http.StatusNotFound},
+ {http.MethodPost, "/credential-vault", http.StatusNotFound},
+ {http.MethodPatch, "/credential-vault", http.StatusNotFound},
+ {http.MethodDelete, "/credential-vault", http.StatusNotFound},
} {
rec := doRequest(t, srv, tc.method, tc.path, `{}`)
- require.Equal(t, http.StatusNotFound, rec.Code, "%s %s must be gone", tc.method, tc.path)
+ require.Equal(t, tc.want, rec.Code, "%s %s", tc.method, tc.path)
}
}
diff --git a/components/egress/fastsandbox_vault_persist.go b/components/egress/fastsandbox_vault_persist.go
index 0c7b23c54..cdd02fd10 100644
--- a/components/egress/fastsandbox_vault_persist.go
+++ b/components/egress/fastsandbox_vault_persist.go
@@ -67,48 +67,80 @@ type vaultPersistence struct {
// the volume joins the credential trust surface) and sweeps staged leftovers:
// startup loads the committed files only.
func newVaultPersistence(dir string) (*vaultPersistence, error) {
+ if err := prepareStateDir(dir, "vault"); err != nil {
+ return nil, err
+ }
+ return &vaultPersistence{
+ dir: dir,
+ newFile: func(path string) (vaultFileStore, error) { return policy.NewAtomicPolicyFile(path) },
+ files: make(map[subject.Subject]vaultFileStore),
+ }, nil
+}
+
+// prepareStateDir validates and prepares one per-subject state directory
+// (0700, no symlink, no traversal) for the atomic file machinery: it sweeps
+// staging leftovers a crashed writer left behind, so startup loads the
+// committed files only. noun names the state kind in errors and logs
+// ("vault", "policy").
+func prepareStateDir(dir, noun string) error {
dir = strings.TrimSpace(dir)
if dir == "" {
- return nil, errors.New("vault persistence directory is empty")
+ return fmt.Errorf("%s persistence directory is empty", noun)
}
if !filepath.IsAbs(dir) {
- return nil, fmt.Errorf("vault persistence directory %q must be absolute", dir)
+ return fmt.Errorf("%s persistence directory %q must be absolute", noun, dir)
}
for _, part := range strings.Split(dir, string(os.PathSeparator)) {
if part == ".." {
- return nil, fmt.Errorf("vault persistence directory %q must not traverse parents", dir)
+ return fmt.Errorf("%s persistence directory %q must not traverse parents", noun, dir)
}
}
if err := os.MkdirAll(dir, 0o700); err != nil {
- return nil, fmt.Errorf("prepare vault directory %s: %w", dir, err)
+ return fmt.Errorf("prepare %s directory %s: %w", noun, dir, err)
}
- // Reject a symlinked vault directory BEFORE chmod/sweep act through it
+ // Reject a symlinked state directory BEFORE chmod/sweep act through it
// (the per-file atomic machinery re-validates no-follow on every real
- // vault op; this keeps startup from mutating a link target first).
+ // op; this keeps startup from mutating a link target first).
if info, err := os.Lstat(dir); err != nil {
- return nil, fmt.Errorf("inspect vault directory %s: %w", dir, err)
+ return fmt.Errorf("inspect %s directory %s: %w", noun, dir, err)
} else if info.Mode()&os.ModeSymlink != 0 {
- return nil, fmt.Errorf("vault persistence directory %q must not be a symlink", dir)
+ return fmt.Errorf("%s persistence directory %q must not be a symlink", noun, dir)
} else if !info.IsDir() {
- return nil, fmt.Errorf("vault persistence directory %q is not a directory", dir)
+ return fmt.Errorf("%s persistence directory %q is not a directory", noun, dir)
}
// An existing directory may carry wider bits from a previous generation.
if err := os.Chmod(dir, 0o700); err != nil {
- return nil, fmt.Errorf("restrict vault directory %s: %w", dir, err)
+ return fmt.Errorf("restrict %s directory %s: %w", noun, dir, err)
}
// The volume root must pass the atomic machinery's trusted-ancestor
// check; kubelet creates emptyDir roots 0777, which fails it.
if err := restrictVolumeRoot(dir); err != nil {
- return nil, err
+ return err
}
- if err := sweepVaultTempFiles(dir); err != nil {
- return nil, fmt.Errorf("sweep staged vault leftovers in %s: %w", dir, err)
+ if err := sweepStateTempFiles(dir, noun); err != nil {
+ return fmt.Errorf("sweep staged %s leftovers in %s: %w", noun, dir, err)
}
- return &vaultPersistence{
- dir: dir,
- newFile: func(path string) (vaultFileStore, error) { return policy.NewAtomicPolicyFile(path) },
- files: make(map[subject.Subject]vaultFileStore),
- }, nil
+ return nil
+}
+
+// sweepStateTempFiles unlinks staging files a crashed writer left behind
+// (rename never attempted — unconfirmed candidate state).
+func sweepStateTempFiles(dir, noun string) error {
+ entries, err := os.ReadDir(dir)
+ if err != nil {
+ return err
+ }
+ for _, entry := range entries {
+ name := entry.Name()
+ if entry.IsDir() || !strings.HasPrefix(name, policy.AtomicTempPrefix) || !strings.HasSuffix(name, policy.AtomicTempSuffix) {
+ continue
+ }
+ if err := os.Remove(filepath.Join(dir, name)); err != nil {
+ return fmt.Errorf("discard staged leftover %s: %w", name, err)
+ }
+ log.Infof("%s persistence: discarded staged leftover %s", noun, name)
+ }
+ return nil
}
// restrictVolumeRoot clears group/world-write bits from the vault volume
@@ -149,21 +181,7 @@ func restrictVolumeRoot(dir string) error {
// sweepVaultTempFiles unlinks staging files a crashed writer left behind
// (rename never attempted — unconfirmed candidate state).
func sweepVaultTempFiles(dir string) error {
- entries, err := os.ReadDir(dir)
- if err != nil {
- return err
- }
- for _, entry := range entries {
- name := entry.Name()
- if entry.IsDir() || !strings.HasPrefix(name, policy.AtomicTempPrefix) || !strings.HasSuffix(name, policy.AtomicTempSuffix) {
- continue
- }
- if err := os.Remove(filepath.Join(dir, name)); err != nil {
- return fmt.Errorf("discard staged leftover %s: %w", name, err)
- }
- log.Infof("vault persistence: discarded staged leftover %s", name)
- }
- return nil
+ return sweepStateTempFiles(dir, "vault")
}
// vaultFileUID strips the internal "s-" prefix: the file contract names files
diff --git a/components/egress/fastsandbox_vault_snapshot.go b/components/egress/fastsandbox_vault_snapshot.go
index 42180b82f..8cc5c3918 100644
--- a/components/egress/fastsandbox_vault_snapshot.go
+++ b/components/egress/fastsandbox_vault_snapshot.go
@@ -50,13 +50,19 @@ var errVaultSnapshotTooLarge = fmt.Errorf("vault bundle file exceeds %d bytes",
// inside the vault persistence directory — reserved for per-subject vault
// files (an export target there could clobber another subject's vault).
func (p *vaultPersistence) reservesPath(path string) bool {
- rel, err := filepath.Rel(filepath.Clean(p.dir), filepath.Clean(path))
+ return reservesPathUnder(p.dir, path)
+}
+
+// reservesPathUnder is the shared path-reservation check for the per-subject
+// state directories: only the parent chain may be outside; children whose
+// names begin with dots (e.g. "..victim.json") are inside the reserved
+// subtree. Uncomparable paths fail closed.
+func reservesPathUnder(dir, path string) bool {
+ rel, err := filepath.Rel(filepath.Clean(dir), filepath.Clean(path))
if err != nil {
// Uncomparable — fail closed.
return true
}
- // Only the parent chain is outside; children whose names begin with
- // dots (e.g. "..victim.json") are inside the reserved subtree.
return rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator))
}
diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.go
index 7e7d5d40b..a6c82a602 100644
--- a/components/egress/pkg/actionhandler/actionhandler.go
+++ b/components/egress/pkg/actionhandler/actionhandler.go
@@ -16,8 +16,9 @@
// protocol (docs/concepts/sandbox-actions.md, sandbox.fast.io/actions/v1)
// from the egress side: the egress process IS the Handler, and the Fastlet
// delivers Binding synchronization (SET_BINDING / REMOVE_BINDING), Lifecycle
-// Hooks, and the pause/resume vault snapshot transfer (VAULT_EXPORT /
-// VAULT_IMPORT) over two Pod-loopback HTTP endpoints.
+// Hooks, and the pause/resume snapshot transfer (VAULT_EXPORT / VAULT_IMPORT
+// for the credential vault, POLICY_EXPORT / POLICY_IMPORT for the recorded
+// egress policy) over two Pod-loopback HTTP endpoints.
//
// The package owns the wire model, parsing, and validation only. Lifecycle
// semantics (deny-first registration, data-plane-ready activation) are wired
@@ -56,6 +57,13 @@ const (
// transfer.
OperationVaultExport Operation = "VAULT_EXPORT"
OperationVaultImport Operation = "VAULT_IMPORT"
+ // PolicyExport/Import carry the subject's persisted egress policy across
+ // pause/resume with the same contract as the vault transfer: export into
+ // the snapshot bundle before teardown, import re-stamped before
+ // data-plane-ready — the only authorized incarnation transfer for the
+ // recorded policy.
+ OperationPolicyExport Operation = "POLICY_EXPORT"
+ OperationPolicyImport Operation = "POLICY_IMPORT"
)
// Lifecycle Hook names (v1). Unknown Hook names are rejected: the Handler
@@ -217,7 +225,8 @@ func (e *Envelope) Validate() error {
}
case OperationRemoveBinding:
// no payload required; terminal cleanup is identified by the sandbox ref
- case OperationVaultExport, OperationVaultImport:
+ case OperationVaultExport, OperationVaultImport,
+ OperationPolicyExport, OperationPolicyImport:
if e.Snapshot == nil || strings.TrimSpace(e.Snapshot.Path) == "" {
return fmt.Errorf("%s requires a snapshot payload with a path", e.Operation)
}
@@ -291,4 +300,13 @@ type StatusResponse struct {
// as false: the Fastlet then skips the transfer (checkpoint proceeds
// without a vault) instead of failing it.
VaultTransfer bool `json:"vaultTransfer,omitempty"`
+ // PolicyTransfer reports that this Handler serves POLICY_EXPORT /
+ // POLICY_IMPORT and persists per-subject policy files (same shape as
+ // VaultTransfer). Absent decodes as false: the Fastlet skips the
+ // policy transfer instead of failing the checkpoint.
+ PolicyTransfer bool `json:"policyTransfer,omitempty"`
+ // PolicyRecovery is true while the policy persistence recovery latch
+ // freezes policy relay writes until restart (same mechanics as
+ // vaultRecovery).
+ PolicyRecovery bool `json:"policyRecovery,omitempty"`
}
diff --git a/components/egress/pkg/constants/configuration.go b/components/egress/pkg/constants/configuration.go
index 4eecf6482..0cbacd161 100644
--- a/components/egress/pkg/constants/configuration.go
+++ b/components/egress/pkg/constants/configuration.go
@@ -60,17 +60,29 @@ const (
// server↔egress contract terminated by the FastPath handler-relay. Every op
// may carry the expectedIncarnation precondition (the owning runtime
// instance recorded at SET_BINDING); a mismatch is a 412.
+//
+// Relay policy surface mirrors the vault relay: /policy/{sandboxUid}
+// terminates the same handler-relay channel for the subject's recorded
+// egress policy (full replace with an optional expectedRevision, deny-first
+// on DELETE).
const (
EgressVaultIncarnationHeader = "X-Fast-Sandbox-Incarnation"
VaultRelayPathPrefix = "/vault/"
+
+ PolicyRelayPathPrefix = "/policy/"
)
// EnvEgressVaultDir (fast-sandbox profile): directory for the per-subject
// vault files on the Pod-scoped emptyDir volume. Empty/unset keeps the vault
// memory-only; the sidecar profile never persists.
+//
+// EnvEgressPolicyDir (fast-sandbox profile): directory for the per-subject
+// policy files with the same semantics. Persistence is required for the
+// POLICY_EXPORT / POLICY_IMPORT snapshot transfer.
const (
- EnvEgressVaultDir = "OPENSANDBOX_EGRESS_VAULT_DIR"
+ EnvEgressVaultDir = "OPENSANDBOX_EGRESS_VAULT_DIR"
+ EnvEgressPolicyDir = "OPENSANDBOX_EGRESS_POLICY_DIR"
)
const (
diff --git a/components/egress/pkg/policy/policyfile.go b/components/egress/pkg/policy/policyfile.go
new file mode 100644
index 000000000..afad8cf2c
--- /dev/null
+++ b/components/egress/pkg/policy/policyfile.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.
+
+// The per-subject egress policy file format: a versioned persistence
+// contract, one file per subject at <egress-volume>/policy/<sandboxUid>.json.
+// The shape mirrors the credential vault file (pkg/credentialvault): a
+// versioned envelope stamped with the owning runtime fence, the revision,
+// and the recorded policy body.
+package policy
+
+import (
+ "bytes"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+)
+
+// PolicyFileVersion is the only supported on-disk schema version. Anything
+// else — including a missing one — is rejected rather than misinterpreted;
+// the rejection is identifiable via ErrUnsupportedPolicyFileVersion so
+// callers can preserve files written by a newer consumer.
+const PolicyFileVersion = 1
+
+// MaxPolicyBodyBytes bounds one recorded policy body: the fast-sandbox
+// Sandbox CRD caps every action binding input at 64 KiB, and the relay
+// surface carries exactly that policy.
+const MaxPolicyBodyBytes = 64 << 10
+
+// MaxEncodedPolicyFileBytes bounds one encoded policy file: a relay body up
+// to MaxPolicyBodyBytes plus the envelope (version, fence, revision, JSON
+// framing). Consumers sizing storage or transfers for policy files use this
+// instead of re-deriving the body limit.
+const MaxEncodedPolicyFileBytes = MaxPolicyBodyBytes + 4<<10
+
+// ErrUnsupportedPolicyFileVersion marks a DecodePolicyFile failure caused
+// solely by an unknown schema version — structurally fine for a newer
+// reader.
+var ErrUnsupportedPolicyFileVersion = errors.New("unsupported policy file version")
+
+// PolicyFile is the versioned envelope of one subject's persisted policy
+// revision. Incarnation + AttachmentID record the owning runtime fence from
+// the SET_BINDING envelope; a registration under a different fence — a
+// reset, or a rebind that changed only the attachment — finds the file
+// stale.
+type PolicyFile struct {
+ Version int `json:"v"`
+ Incarnation string `json:"incarnation"`
+ AttachmentID string `json:"attachmentId"`
+ Revision int64 `json:"revision"`
+ Policy json.RawMessage `json:"policy"`
+}
+
+// EncodePolicyFile renders the canonical bytes: version pinned to
+// PolicyFileVersion, the owning runtime fence, the revision, and the policy
+// body. The body must already be canonical JSON (the encoded NetworkPolicy)
+// and is stored verbatim so a decoded file re-parses to the same policy.
+// The output ends with a trailing newline, matching the policy file
+// convention.
+func EncodePolicyFile(incarnation, attachmentID string, revision int64, body []byte) ([]byte, error) {
+ incarnation = strings.TrimSpace(incarnation)
+ if incarnation == "" {
+ return nil, fmt.Errorf("policy file incarnation cannot be blank")
+ }
+ attachmentID = strings.TrimSpace(attachmentID)
+ if attachmentID == "" {
+ return nil, fmt.Errorf("policy file attachmentId cannot be blank")
+ }
+ if revision < 1 {
+ return nil, fmt.Errorf("policy file revision %d must be positive", revision)
+ }
+ if !json.Valid(body) {
+ return nil, fmt.Errorf("policy file body is not valid JSON")
+ }
+ out, err := json.Marshal(PolicyFile{
+ Version: PolicyFileVersion,
+ Incarnation: incarnation,
+ AttachmentID: attachmentID,
+ Revision: revision,
+ Policy: bytes.TrimSpace(body),
+ })
+ if err != nil {
+ return nil, fmt.Errorf("encode policy file envelope: %w", err)
+ }
+ return append(out, '\n'), nil
+}
+
+// DecodePolicyFile parses and validates file bytes, returning the envelope
+// and the raw policy body. The version discriminator is read FIRST with a
+// tolerant view: a newer envelope carries unknown fields, so the strict v1
+// schema must not reject (and the caller quarantine) a file this reader
+// should merely preserve. Only strictly newer versions surface
+// ErrUnsupportedPolicyFileVersion; a missing or invalid version is plain
+// corruption. Semantic policy validation (ParsePolicy) is the caller's job —
+// the file contract only pins the envelope.
+func DecodePolicyFile(data []byte) (PolicyFile, json.RawMessage, error) {
+ trimmed := bytes.TrimSpace(data)
+ if len(trimmed) == 0 {
+ return PolicyFile{}, nil, fmt.Errorf("policy file is empty")
+ }
+ var disc struct {
+ Version *int `json:"v"`
+ }
+ if err := json.Unmarshal(trimmed, &disc); err != nil {
+ return PolicyFile{}, nil, fmt.Errorf("decode policy file envelope: %w", err)
+ }
+ if disc.Version != nil && *disc.Version > PolicyFileVersion {
+ return PolicyFile{}, nil, fmt.Errorf("%w %d (newer than supported %d)", ErrUnsupportedPolicyFileVersion, *disc.Version, PolicyFileVersion)
+ }
+ var pf PolicyFile
+ dec := json.NewDecoder(bytes.NewReader(trimmed))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&pf); err != nil {
+ return PolicyFile{}, nil, fmt.Errorf("decode policy file envelope: %w", err)
+ }
+ if pf.Version != PolicyFileVersion {
+ return PolicyFile{}, nil, fmt.Errorf("invalid policy file version %d (want %d)", pf.Version, PolicyFileVersion)
+ }
+ if strings.TrimSpace(pf.Incarnation) == "" {
+ return PolicyFile{}, nil, fmt.Errorf("policy file incarnation cannot be blank")
+ }
+ if strings.TrimSpace(pf.AttachmentID) == "" {
+ return PolicyFile{}, nil, fmt.Errorf("policy file attachmentId cannot be blank")
+ }
+ if pf.Revision < 1 {
+ return PolicyFile{}, nil, fmt.Errorf("policy file revision %d must be positive", pf.Revision)
+ }
+ if len(pf.Policy) == 0 {
+ return PolicyFile{}, nil, fmt.Errorf("policy file body is missing")
+ }
+ return pf, pf.Policy, nil
+}
diff --git a/components/egress/pkg/policy/policyfile_test.go b/components/egress/pkg/policy/policyfile_test.go
new file mode 100644
index 000000000..5492db54e
--- /dev/null
+++ b/components/egress/pkg/policy/policyfile_test.go
@@ -0,0 +1,96 @@
+// 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 policy
+
+import (
+ "encoding/json"
+ "errors"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestPolicyFileRoundTrip(t *testing.T) {
+ body := json.RawMessage(`{"defaultAction":"deny","egress":[{"action":"allow","target":"api.example.com"}]}`)
+ raw, err := EncodePolicyFile("runtime-1", "attachment-1", 7, body)
+ require.NoError(t, err)
+ assert.True(t, strings.HasSuffix(string(raw), "\n"), "trailing newline, matching the policy file convention")
+
+ pf, decoded, err := DecodePolicyFile(raw)
+ require.NoError(t, err)
+ assert.Equal(t, PolicyFileVersion, pf.Version)
+ assert.Equal(t, "runtime-1", pf.Incarnation)
+ assert.Equal(t, "attachment-1", pf.AttachmentID)
+ assert.Equal(t, int64(7), pf.Revision)
+ assert.JSONEq(t, string(body), string(decoded))
+
+ // The decoded body parses to the same policy the caller encoded.
+ pol, err := ParsePolicy(string(decoded))
+ require.NoError(t, err)
+ assert.Equal(t, "allow", pol.Evaluate("api.example.com"))
+}
+
+func TestPolicyFileEncodeValidation(t *testing.T) {
+ body := json.RawMessage(`{}`)
+ cases := []struct {
+ name string
+ incarnation string
+ attachmentID string
+ revision int64
+ body json.RawMessage
+ }{
+ {"blank incarnation", " ", "a", 1, body},
+ {"blank attachment", "r", " ", 1, body},
+ {"zero revision", "r", "a", 0, body},
+ {"negative revision", "r", "a", -1, body},
+ {"invalid json body", "r", "a", 1, json.RawMessage(`{`)},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ _, err := EncodePolicyFile(tc.incarnation, tc.attachmentID, tc.revision, tc.body)
+ assert.Error(t, err)
+ })
+ }
+}
+
+func TestPolicyFileDecodeValidation(t *testing.T) {
+ t.Run("empty", func(t *testing.T) {
+ _, _, err := DecodePolicyFile(nil)
+ assert.ErrorContains(t, err, "empty")
+ })
+ t.Run("missing version", func(t *testing.T) {
+ _, _, err := DecodePolicyFile([]byte(`{"incarnation":"r","attachmentId":"a","revision":1,"policy":{}}` + "\n"))
+ assert.ErrorContains(t, err, "version")
+ })
+ t.Run("unknown fields rejected", func(t *testing.T) {
+ _, _, err := DecodePolicyFile([]byte(`{"v":1,"incarnation":"r","attachmentId":"a","revision":1,"policy":{},"extra":true}` + "\n"))
+ assert.Error(t, err)
+ })
+ t.Run("newer version is identifiable", func(t *testing.T) {
+ _, _, err := DecodePolicyFile([]byte(`{"v":2,"incarnation":"r","attachmentId":"a","revision":1,"policy":{},"ct":"x"}` + "\n"))
+ require.Error(t, err)
+ assert.True(t, errors.Is(err, ErrUnsupportedPolicyFileVersion))
+ })
+ t.Run("missing body", func(t *testing.T) {
+ _, _, err := DecodePolicyFile([]byte(`{"v":1,"incarnation":"r","attachmentId":"a","revision":1}` + "\n"))
+ assert.ErrorContains(t, err, "body is missing")
+ })
+ t.Run("non-positive revision", func(t *testing.T) {
+ _, _, err := DecodePolicyFile([]byte(`{"v":1,"incarnation":"r","attachmentId":"a","revision":0,"policy":{}}` + "\n"))
+ assert.ErrorContains(t, err, "must be positive")
+ })
+}