Secure, Fast, and Extensible Sandbox runtime for AI agents.
docs(egress): tighten the comment prose across the policy/vault surfaces
高然6f85c19dd633
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.goindex 29eb1953b..7ddd0ca73 100644--- a/components/egress/fastsandbox_actions.go+++ b/components/egress/fastsandbox_actions.go@@ -21,13 +21,13 @@//// Operation mapping://-// SET_BINDING register the subject (deny-first), store the input-// policy as pending; activate immediately when the-// subject is already active (a plain input update does-// not replay Hooks). A JSON-null input removes the-// policy and reverts to deny-first. A key held by a-// different live subject is a stale-subject takeover-// (OSEP-0022): the previous owner goes first.+// SET_BINDING register the subject (deny-first) and seed the input+// policy on a fresh subject (an existing record+// supersedes the input); activate immediately when the+// subject is already active. A JSON-null input removes+// the policy and reverts to deny-first. A key held by+// a different live subject is a stale-subject+// takeover (OSEP-0022): the previous owner goes first.// LIFECYCLE_HOOK sandbox.runtime-ready only confirms the deny-first// install (idempotent); sandbox.data-plane-ready applies// the pending policy -> active. Unknown Hooks are@@ -197,15 +197,12 @@ func (s *fastSandboxPolicyServer) applySetBinding(env *actionhandler.Envelope) (return http.StatusBadRequest, fmt.Errorf("invalid binding input policy: %v", err)}}- // The WHOLE mutation runs under policyCommitMu — rebind purge,- // registration, and the seed/apply are one serialized unit against the- // relay commits and the hook activation. Without this, a- // predecessor-identity relay write holding policyCommitMu could- // straddle the rebind's fence flip: its apply closure passes the fence- // checks pre-registration, then its reg.ApplyPolicy lands on the- // SUCCESSOR's registry entry after RegisterAndEnforce — the successor- // would go active under the predecessor's policy. Lock order:- // policyCommitMu → registry → s.mu (matches the commit paths).+ // The whole mutation holds policyCommitMu — rebind purge, registration,+ // and seed/apply are one unit against relay commits and hooks.+ // Otherwise a predecessor-identity relay write could straddle the+ // fence flip and its reg.ApplyPolicy would activate the successor+ // under the predecessor's policy. Lock order: policyCommitMu →+ // registry → s.mu.s.policyCommitMu.Lock()defer s.policyCommitMu.Unlock()diff --git a/components/egress/fastsandbox_policy.go b/components/egress/fastsandbox_policy.goindex 75cb3ddda..6da93af89 100644--- a/components/egress/fastsandbox_policy.go+++ b/components/egress/fastsandbox_policy.go@@ -12,26 +12,11 @@// 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 on-// writes (GET keeps serving the in-memory record). 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).+// Relay policy surface: /policy/{sandboxUid} — the runtime twin of the+// vault relay. The binding input seeds the policy at create; the relay owns+// every runtime mutation. GET returns the recorded policy + revision; PUT+// is a full replace (optional expectedRevision); DELETE reverts to+// default-deny. Every write runs persist → apply → ack.package mainimport (@@ -48,12 +33,11 @@ import ()// policyEntry records the per-subject policy bookkeeping: the revision the-// relay preconditions fence on, the runtime fence the record was-// materialized under, and the sealed flag. The policy itself lives in the-// registry (active subjects) or pendingPolicies (denying subjects). A-// record is authoritative once it exists: the binding input only ever-// seeds a fresh subject, and every later policy change goes through the-// relay or the snapshot transfer — exactly like the vault.+// relay preconditions fence on, the runtime fence, and the state flags. The+// policy itself lives in the registry (active) or pendingPolicies+// (denying). A record is authoritative once it exists: the binding input+// only ever seeds a fresh subject — later changes ride the relay or the+// snapshot transfer, like the vault.type policyEntry struct {revision int64fence subject.Fencing@@ -104,20 +88,13 @@ func (s *fastSandboxPolicyServer) handlePolicyRelay(w http.ResponseWriter, r *ht}}-// selectRelayPolicy decides registration, the expectedIncarnation-// precondition, the seal, and the recorded policy. Registry reads happen-// BEFORE s.mu — the lock order is registry → s.mu everywhere (the takeover-// path holds the registry write lock while purging subject state under-// s.mu; the reverse order deadlocks the DNS hot path). A fence change-// between the read and the lock is bounded: the purge removes the record,-// and the write paths re-validate the fence at commit time.+// selectRelayPolicy serves GET: registration, expectedIncarnation, seal,+// and the recorded policy. Held across the whole read so the policy body+// and its revision come from the same commit (the server's GET→merge→PUT+// PATCH uses the revision as its precondition). Lock order:+// policyCommitMu → registry → s.mu (see fastsandbox_server.go's takeover+// path; the reverse order deadlocks the DNS hot path).func (s *fastSandboxPolicyServer) selectRelayPolicy(r *http.Request, subj subject.Subject) (*policyRelayDocument, int, string) {- // Serialized with the policy commits: the policy body and its revision- // must come from the SAME commit, or a GET overlapping a PUT would pair- // the old policy with the new revision — and the server's GET→merge→PUT- // PATCH would then present that revision and overwrite the concurrent- // replacement. Lock order: policyCommitMu → registry → s.mu (matches- // the commit paths).s.policyCommitMu.Lock()defer s.policyCommitMu.Unlock()fence, ok := s.reg.Fence(subj)@@ -154,15 +131,9 @@ func (s *fastSandboxPolicyServer) selectRelayPolicy(r *http.Request, subj subjec}// 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.+// DELETE (revert to default-deny). The body is parsed and validated before+// policyCommitMu is taken (a stalled or invalid client must never hold+// it); the whole write — guards, decision, commit — serializes on it.func (s *fastSandboxPolicyServer) handlePolicyRelayWrite(w http.ResponseWriter, r *http.Request, subj subject.Subject) {var doc policyRelayDocumentif r.Method == http.MethodPut {@@ -204,18 +175,13 @@ func (s *fastSandboxPolicyServer) handlePolicyRelayWrite(w http.ResponseWriter,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.+ // The decision must be commit-atomic or two racing replaces could land+ // the same revision. Enforcement in the apply closures never runs+ // under s.mu (it takes the registry write lock).s.policyCommitMu.Lock()defer s.policyCommitMu.Unlock()- // Registry reads before s.mu (lock order: registry → s.mu, see- // selectRelayPolicy); the commit-time target re-check closes the TOCTOU.+ // Registry reads before s.mu (lock order: registry → s.mu).fence, ok := s.reg.Fence(subj)if !ok {http.Error(w, "unknown subject", http.StatusNotFound)@@ -225,8 +191,6 @@ func (s *fastSandboxPolicyServer) handlePolicyRelayWrite(w http.ResponseWriter,http.Error(w, "expectedIncarnation mismatch", http.StatusPreconditionFailed)return}- // Guards + decision under one s.mu hold, serialized against rebinds and- // terminal purges (the whole write already holds policyCommitMu).s.mu.Lock()if !s.fenceMatchesLocked(subj, fence) {s.mu.Unlock()@@ -293,13 +257,10 @@ func relayPolicyPrecondition(doc *policyRelayDocument) (expected *int64, err errreturn 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, and the data-plane-ready hook-// serializes on the same mutex). The apply closure re-reads the lifecycle-// state and the registration fence — both can change between the guard-// phase and this commit (a concurrent hook activation, a rebind) — so the-// recorded state can never diverge from what was actually enforced.+// putRelayPolicy commits a full replace: persist → apply → ack. The caller+// holds policyCommitMu (guards and commit are one serialized unit). The+// apply closure re-reads the lifecycle state and fence at apply time —+// both can change between the guards and the commit.func (s *fastSandboxPolicyServer) putRelayPolicy(w http.ResponseWriter, r *http.Request, subj subject.Subject, fence subject.Fencing, pol *policy.NetworkPolicy, newRev int64, created bool) {raw, err := json.Marshal(pol)if err != nil {@@ -322,13 +283,10 @@ func (s *fastSandboxPolicyServer) putRelayPolicy(w http.ResponseWriter, r *http.}}s.mu.Lock()- // The pending slot mirrors what is enforced in BOTH states: on a- // denying subject it is the barrier's payload; on an active one it- // keeps an at-least-once data-plane-ready replay idempotent (a- // stale deny tombstone must never re-enforce over the replacement).+ // The pending slot mirrors what is enforced, so a replayed+ // data-plane-ready is idempotent.s.pendingPolicies[subj] = pol- // A fresh entry also clears a degraded mark: the successful write- // IS the heal.+ // A fresh entry also clears a degraded mark: the write IS the heal.s.policies[subj] = &policyEntry{revision: newRev, fence: fence}s.mu.Unlock()return nil@@ -361,12 +319,10 @@ func (s *fastSandboxPolicyServer) putRelayPolicy(w http.ResponseWriter, r *http.writeJSON(w, putResponseStatus(created), doc)}-// policyCommitTarget re-reads the subject's lifecycle state and verifies-// the registration fence still matches the commit's — the data-plane-ready-// activation and rebinds run outside the commit serialization, so a stale-// apply must be aborted (the commit protocol rolls the file back) instead-// of landing on the wrong identity or state. Registry reads only: no s.mu-// (lock order: registry → s.mu, see selectRelayPolicy).+// policyCommitTarget re-reads the lifecycle state and registration fence at+// apply time: activation and rebinds run outside the commit serialization,+// so a stale apply aborts (the protocol rolls the file back) instead of+// landing on the wrong identity or state. Registry reads only — no s.mu.func (s *fastSandboxPolicyServer) policyCommitTarget(subj subject.Subject, fence subject.Fencing) (subject.State, error) {regFence, ok := s.reg.Fence(subj)if !ok || regFence != fence {@@ -385,13 +341,12 @@ func putResponseStatus(created bool) int {return http.StatusOK}-// deleteRelayPolicy commits the deletion as an authoritative default-deny-// tombstone: the record persists at the successor revision (memory + file)-// and enforcement becomes default-deny — in place on an active subject-// (which stays active, so a later relay PUT re-enables immediately), held-// pending on a denying one. An egress restart reloads the tombstone-// instead of letting the replayed bootstrap binding resurrect the deleted-// policy. GET serves the deny record. The caller holds policyCommitMu.+// deleteRelayPolicy commits deletion as an authoritative default-deny+// tombstone: the record persists at the successor revision, so a restart+// reloads the deletion instead of letting the replayed bootstrap binding+// resurrect the removed policy. On an active subject the deny applies in+// place (stays active, so a later PUT re-enables immediately); on a+// denying one it is held pending. The caller holds policyCommitMu.func (s *fastSandboxPolicyServer) deleteRelayPolicy(w http.ResponseWriter, subj subject.Subject, fence subject.Fencing, newRev int64) {deny := policy.DefaultDenyPolicy()apply := func() error {@@ -400,22 +355,16 @@ func (s *fastSandboxPolicyServer) deleteRelayPolicy(w http.ResponseWriter, subjreturn err}if state == subject.StateActive {- // Enforcement first: the deny tombstone applies IN PLACE — the- // subject stays active with default-deny enforced (the operator- // always overlay keeps applying), so a later relay PUT- // re-enables traffic immediately; the generic handler relay- // never replays a data-plane-ready hook to activate a- // pending-only replacement. nft commits before the registry- // state (fail-closed transition).+ // Enforcement first (nft commits before the registry state).+ // The subject stays active, so a later PUT re-enables without+ // a hook replay.if err := s.applyPolicy(subj, deny); err != nil {return err}}s.mu.Lock()- // The activation barrier keeps working across a hook replay: a- // replayed data-plane-ready activates the deny record, never a- // stale policy. On an active subject the pending deny is- // idempotent with what was just enforced.+ // A replayed data-plane-ready activates the tombstone, never a+ // stale policy.s.pendingPolicies[subj] = denys.policies[subj] = &policyEntry{revision: newRev, fence: fence}s.mu.Unlock()diff --git a/components/egress/fastsandbox_policy_persist.go b/components/egress/fastsandbox_policy_persist.goindex c164c476b..1a80a394f 100644--- a/components/egress/fastsandbox_policy_persist.go+++ b/components/egress/fastsandbox_policy_persist.go@@ -291,18 +291,11 @@ func (s *fastSandboxPolicyServer) policyHealthIssue() string {return ""}-// clearPolicyRecord removes the subject's recorded policy (binding removal-// on a still-live sandbox): the in-memory record and pending policy go, and-// the persisted file is purged so the deny-first state is also the durable-// state. An uncertain/failed purge falls back to persisting a default-deny-// tombstone at the successor revision — a leftover file whose recorded-// content still matches the removed policy would otherwise be loaded by a-// later same-fence registration or restart, resurrecting an acknowledged--// away policy. A tombstone persist failure latches recovery (writes frozen-// until restart). Serialized with the relay commits (policyCommitMu) so an-// in-flight write against the removed binding cannot recreate the record-// after the purge. The caller holds policyCommitMu (the SET_BINDING-// mutation hold); never call under the registry write lock.+// clearPolicyRecordLocked removes the recorded policy (binding removal on a+// still-live sandbox). A failed purge falls back to a default-deny+// tombstone — a leftover file would otherwise resurrect the removed policy+// at the next same-fence registration; a tombstone persist failure latches+// recovery. The caller holds policyCommitMu.func (s *fastSandboxPolicyServer) clearPolicyRecordLocked(subj subject.Subject) error {s.mu.Lock()entry := s.policies[subj]@@ -358,25 +351,17 @@ func (s *fastSandboxPolicyServer) clearPolicyRecordLocked(subj subject.Subject)// (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 record materializes from the file-// - mismatch → stale, purged (a reset never inherits the predecessor's-// policy)-// - unreadable, a newer schema, or content that fails to parse → the-// subject DEGRADES fail-closed: the pending policy becomes default-deny-// and the degraded mark surfaces on the actions status (a successful-// relay PUT heals it). The file may carry an acknowledged runtime-// change this egress can no longer read — the bootstrap input could be-// more permissive, so it must not seed+// - fence match → the file is authoritative (the replayed input carries+// only the bootstrap policy, never relay mutations)+// - mismatch → stale, purged+// - unreadable, a newer schema, or unparseable → the subject DEGRADES+// fail-closed (pending default-deny, healed by a relay PUT) — the+// bootstrap input could be more permissive than the unreadable runtime+// change, so it must not seed//-// 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.+// Removal SET_BINDINGS skip the reload (clearPolicyRecordLocked). A live+// record for this exact fence wins (duplicate SET_BINDING). Runs BEFORE+// RegisterAndEnforce, mirroring rehydrateVaultReload.func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fence subject.Fencing) {s.mu.Lock()defer s.mu.Unlock()@@ -460,13 +445,10 @@ func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fe}// applyBindingPolicyLocked seeds the binding's policy for a freshly-// registered subject (record absent) through the same commit protocol as-// the relay writes. The caller holds policyCommitMu (the SET_BINDING-// mutation hold). A subject with an existing record never reads its-// binding input again: the recorded policy — seeded once, then owned by the relay writes-// and the snapshot transfer — is authoritative, exactly like the vault-// slice. Binding replays (at-least-once delivery, egress restarts, and the-// superseded CRD-driven update path) are therefore policy no-ops.+// registered subject (record absent). A subject with an existing record+// never reads its binding input again — the recorded policy is+// authoritative, like the vault slice — so binding replays are policy+// no-ops. The caller holds policyCommitMu.func (s *fastSandboxPolicyServer) applyBindingPolicyLocked(subj subject.Subject, fence subject.Fencing, pol *policy.NetworkPolicy, stateActive bool) error {s.mu.Lock()entry := s.policies[subj]diff --git a/components/egress/fastsandbox_policy_snapshot.go b/components/egress/fastsandbox_policy_snapshot.goindex 07b6f78d0..a2d5c302c 100644--- a/components/egress/fastsandbox_policy_snapshot.go+++ b/components/egress/fastsandbox_policy_snapshot.go@@ -46,21 +46,13 @@ const maxPolicySnapshotBytes = policy.MaxEncodedPolicyFileBytesvar 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.+// applyPolicyExport copies the recorded policy file into the bundle target+// and seals the subject (a subject without a policy file just seals).+// Failures leave it unsealed and enforcement unchanged — the driver fails+// the pause checkpoint and retries. Three phases, the guarded ones+// serialized with the relay commits: guards + source image, the copy, then+// re-check + seal (source changed mid-copy → 409; the recovery latch+// rejects the export in both guarded phases).func (s *fastSandboxPolicyServer) applyPolicyExport(env *actionhandler.Envelope) (int, error) {subj := subject.FromSandboxUID(env.Sandbox.UID)fence := subject.FromRevision(env)@@ -205,19 +197,13 @@ func (s *fastSandboxPolicyServer) policyExportSourceImageLocked(subj subject.Subreturn 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 from the bundle;-// 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.+// applyPolicyImport lands the bundle as the subject's policy file,+// re-stamped with the restored fence from the envelope (the only authorized+// incarnation transfer) and installs it file-backed. Delivery is+// at-least-once: a local revision newer than the bundle acks idempotently.+// Unregistered (before SET_BINDING), only the file lands — the+// registration-time reload validates it; registered, 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) {subj := subject.FromSandboxUID(env.Sandbox.UID)fence := subject.FromRevision(env)diff --git a/components/egress/fastsandbox_server.go b/components/egress/fastsandbox_server.goindex 855e8599a..c186fc3fb 100644--- a/components/egress/fastsandbox_server.go+++ b/components/egress/fastsandbox_server.go@@ -69,12 +69,10 @@ type fastSandboxPolicyServer struct {// cleanup (gateway refcounts) even when the REMOVE_BINDING envelope omits// the attachment block.subjAtt map[subject.Subject]actionhandler.NetworkAttachment- // subjFence records the registered fence per subject. It is the- // commit-time re-validation for the relay paths, whose registry reads- // happen BEFORE s.mu (lock order: registry → s.mu): a rebind that- // completed between the pre-read and the lock updates this map, so the- // in-lock comparison rejects the stale request without touching the- // registry under s.mu.+ // subjFence mirrors the registered fence per subject: the relay paths+ // pre-read the registry before s.mu (lock order: registry → s.mu), and+ // this in-lock comparison rejects requests whose pre-read went stale+ // across a rebind.subjFence map[subject.Subject]subject.Fencing// vaultFiles owns the per-subject vault files; nil keeps the vault@@ -99,10 +97,9 @@ type fastSandboxPolicyServer struct {// 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 serializes policy file-commit operations process-wide+ // (relay writers from different 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@@ -257,11 +254,9 @@ 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 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.+// Handler returns the fast-sandbox-profile HTTP mux: the Sandbox Actions+// Handler endpoints, the relay surfaces (/policy/{uid}, /vault/{uid}), and+// the healthz probe. No proxy-route surface.func (s *fastSandboxPolicyServer) Handler() http.Handler {mux := http.NewServeMux()mux.HandleFunc(constants.ActionsStatusPath, s.handleActionsStatus)@@ -388,13 +383,10 @@ func (s *fastSandboxPolicyServer) applyPolicy(subj subject.Subject, pol *policy.s.policyMu.Lock()defer s.policyMu.Unlock()eff := s.reg.EffectiveOf(pol)- // policyApplyTimeout bounds the kernel transaction for every caller- // that runs under policyCommitMu (relay commits, the SET_BINDING seed,- // and the data-plane-ready hook all serialize on it): an unbounded- // deadline would let one slow nft apply head-of-line-block every other- // subject's policy write past the listener's write timeout. The- // registration deny-first install is NOT under that serialization and- // keeps its own 30s budget.+ // Bounded: applyPolicy runs under policyCommitMu, so one slow nft+ // transaction would head-of-line-block every subject's writes. The+ // registration deny-first install is not under that serialization and+ // keeps a 30s budget.nftCtx, cancel := context.WithTimeout(s.ctx, policyApplyTimeout)defer cancel()if err := s.nft.ApplyPolicy(nftCtx, subj, eff); err != nil {@@ -419,18 +411,12 @@ type vaultEntry struct {sealed bool}-// vaultFor returns the per-subject vault, created on first use (rehydrated-// from its persisted file at registration, OSEP-0022 stage 2).-// A store is only valid under the fence it was created with: a mismatch-// (same-UID rebind without REMOVE_BINDING, or a TOCTOU store materialized-// against an unregistered subject) is dropped, never inherited — a reset-// never carries old credentials into a new sandbox (OSEP-0022). The fence-// is PRE-READ by the caller (lock order: registry → s.mu); a fence change-// between the read and the lock is bounded by the rebind purge — the stale-// store is dropped on the next selection either way.+// vaultFor returns the per-subject vault, created on first use. A store is+// only valid under the fence it was created with: a mismatch is dropped,+// never inherited. The fence is pre-read (lock order: registry → s.mu); a+// stale pre-read is bounded by the rebind purge — the store drops on the+// next selection either way.func (s *fastSandboxPolicyServer) vaultFor(subj subject.Subject) *credentialvault.Store {- // Registry read before s.mu (lock order: registry → s.mu, see- // handleVaultRelayWrite).fence, _ := s.reg.Fence(subj)s.mu.Lock()defer s.mu.Unlock()@@ -565,15 +551,13 @@ func (s *fastSandboxPolicyServer) takeoverStaleSubject(stale subject.Subject) er}// dropSubjectState removes every piece of per-subject bookkeeping (vault,-// policy record, pending policy, attachment) plus the persisted vault and-// policy files — terminal cleanup (OSEP-0022: REMOVE_BINDING purges memory +-// file).+// policy record, pending policy, attachment) plus the persisted files —+// terminal cleanup.//-// Deliberately WITHOUT policyCommitMu: one caller (takeoverStaleSubject)-// runs under the registry WRITE lock, and taking policyCommitMu there would-// invert against relay commits (policyCommitMu → registry via applyPolicy).-// Safety comes from the commit paths' fence re-check (policyCommitTarget)-// and the recorded fence fencing out stale files at rehydration.+// Deliberately without policyCommitMu: the takeover caller runs under the+// registry write lock, and taking policyCommitMu there would invert against+// relay commits (policyCommitMu → registry). Safety comes from the commit+// paths' fence re-check and fence-keyed stale-file discards.func (s *fastSandboxPolicyServer) dropSubjectState(subj subject.Subject) {s.mu.Lock()delete(s.vaults, subj)@@ -597,10 +581,9 @@ func (s *fastSandboxPolicyServer) recordBindingState(subj subject.Subject, att as.mu.Unlock()}-// fenceMatchesLocked reports whether the subject's recorded registration-// fence equals the request fence. Callers hold s.mu. A false return means-// the pre-read (registry → s.mu window) went stale: the subject was purged-// or rebound, and the request must not touch its state.+// fenceMatchesLocked reports whether the recorded fence equals the request+// fence (commit-time re-validation for the pre-read window). Callers hold+// s.mu.func (s *fastSandboxPolicyServer) fenceMatchesLocked(subj subject.Subject, fence subject.Fencing) bool {got, ok := s.subjFence[subj]return ok && got == fencediff --git a/components/egress/fastsandbox_vault.go b/components/egress/fastsandbox_vault.goindex 17b8ef004..8888955b0 100644--- a/components/egress/fastsandbox_vault.go+++ b/components/egress/fastsandbox_vault.go@@ -311,11 +311,9 @@ func (s *fastSandboxPolicyServer) vaultSealedLocked(subj subject.Subject) bool {}// vaultValidationPolicy returns the policy a vault op validates against:-// the effective policy of an active subject, or — while the subject is-// still denying — its pending binding policy MERGED with the always-// overlay (the op is held to the data-plane-ready barrier, so validation-// must not depend on hook timing). Call this BEFORE s.mu — it reads the-// registry (lock order: registry → s.mu, see handleVaultRelayWrite).+// the effective policy of an active subject, or the pending policy merged+// with the always overlay while denying (a barrier-held op must not depend+// on hook timing). Call BEFORE s.mu — it reads the registry.func (s *fastSandboxPolicyServer) vaultValidationPolicy(subj subject.Subject) *policy.NetworkPolicy {effective := s.reg.EffectivePolicy(subj)if effective != nil {diff --git a/components/egress/fastsandbox_vault_persist.go b/components/egress/fastsandbox_vault_persist.goindex 5432da9ee..373fd7493 100644--- a/components/egress/fastsandbox_vault_persist.go+++ b/components/egress/fastsandbox_vault_persist.go@@ -143,31 +143,26 @@ func sweepStateTempFiles(dir, noun string) error {return nil}-// stateDirNames are the basenames of the per-subject state directories that-// share one egress volume root, registered at assembly from the CONFIGURED-// paths (the basename is deployment-owned, so it cannot be hardcoded; the-// conventional names stay pre-seeded). restrictVolumeRoot treats registered-// siblings as ours — without this, whichever directory initializes second-// would see the first as foreign, skip the volume-root restriction, and the-// atomic machinery would then reject every file op on the untrusted-// ancestor.+// stateDirNames are the basenames of the per-subject state directories+// sharing one egress volume root, registered at assembly from the CONFIGURED+// paths (the basename is deployment-owned). restrictVolumeRoot treats+// registered siblings as ours — otherwise the second initializer skips the+// volume-root restriction and the atomic machinery rejects every file op on+// the untrusted ancestor.var stateDirNames = map[string]bool{"vault": true,"policy": true,}-// registerStateDirName records a configured state directory basename so the-// volume-root restriction recognizes it as a sibling.+// registerStateDirName records a configured state directory basename.func registerStateDirName(dir string) {stateDirNames[filepath.Base(filepath.Clean(dir))] = true}// restrictVolumeRoot clears group/world-write bits from the state volume-// root (the state directory's parent): kubelet creates emptyDir roots 0777,-// which the atomic machinery rejects as an untrusted ancestor. Sibling-// state directories (stateDirNames) belong to us; a root holding any-// other entry is left untouched — that is the manifest's job — and-// already-restrictive roots are a no-op.+// root: kubelet creates emptyDir roots 0777, which the atomic machinery+// rejects as an untrusted ancestor. Registered siblings belong to us; a+// root holding any other entry is left untouched (the manifest's job).func restrictVolumeRoot(dir, noun string) error {parent := filepath.Dir(dir)info, err := os.Stat(parent)diff --git a/components/egress/fastsandbox_vault_snapshot.go b/components/egress/fastsandbox_vault_snapshot.goindex 52dcee10f..51cc5b3bc 100644--- a/components/egress/fastsandbox_vault_snapshot.go+++ b/components/egress/fastsandbox_vault_snapshot.go@@ -123,9 +123,8 @@ func (s *fastSandboxPolicyServer) applyVaultExport(env *actionhandler.Envelope)}}- // Phase 3: seal only against the exact copied image; the fence is- // re-read fresh (registry before s.mu) so a rebind during the copy- // fails the export.+ // Phase 3: re-check + seal; the fence is re-read fresh so a rebind+ // during the copy fails the export.regFence, registered = s.reg.Fence(subj)s.mu.Lock()defer s.mu.Unlock()diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.goindex 28c637420..92d2f6743 100644--- a/components/egress/pkg/actionhandler/actionhandler.go+++ b/components/egress/pkg/actionhandler/actionhandler.go@@ -57,11 +57,8 @@ 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.+ // PolicyExport/Import carry the recorded policy across pause/resume+ // with the same contract as the vault transfer.OperationPolicyExport Operation = "POLICY_EXPORT"OperationPolicyImport Operation = "POLICY_IMPORT")@@ -301,15 +298,12 @@ type StatusResponse struct {// 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.+ // POLICY_IMPORT and persists per-subject policy files.PolicyTransfer bool `json:"policyTransfer,omitempty"`// PolicyRecovery is true while the policy persistence recovery latch- // freezes policy relay writes until restart (same mechanics as- // vaultRecovery); DegradedPolicies lists subjects whose persisted- // policy failed to load (default-deny fail closed for them; a- // successful relay write clears it).+ // freezes policy relay writes until restart; DegradedPolicies lists+ // subjects whose persisted policy failed to load (default-deny fail+ // closed for them; a relay write heals).PolicyRecovery bool `json:"policyRecovery,omitempty"`DegradedPolicies []string `json:"degradedPolicies,omitempty"`}diff --git a/components/egress/pkg/constants/configuration.go b/components/egress/pkg/constants/configuration.goindex bc498d69d..3dc479a3a 100644--- a/components/egress/pkg/constants/configuration.go+++ b/components/egress/pkg/constants/configuration.go@@ -78,9 +78,8 @@ const (// memory-only; the sidecar profile never persists.//// EnvEgressPolicyDir (fast-sandbox profile): REQUIRED — directory for the-// per-subject policy files. The recorded policy is egress-held state; there-// is no memory-only posture (the profile fails startup without it), so the-// binding input never becomes a policy recovery source.+// per-subject policy files. The recorded policy is egress-held state; the+// profile fails startup without it.const (EnvEgressVaultDir = "OPENSANDBOX_EGRESS_VAULT_DIR"EnvEgressPolicyDir = "OPENSANDBOX_EGRESS_POLICY_DIR"diff --git a/server/opensandbox_server/services/fast_sandbox/policy_relay.py b/server/opensandbox_server/services/fast_sandbox/policy_relay.pyindex 696b18f30..cead452ea 100644--- a/server/opensandbox_server/services/fast_sandbox/policy_relay.py+++ b/server/opensandbox_server/services/fast_sandbox/policy_relay.py@@ -22,7 +22,7 @@ the revision state machine):- ``PATCH`` composed server-side: relay ``GET`` → merge in memory → relay``PUT`` carrying the read revision as ``expectedRevision`` (theper-sandbox in-process lock serializes local merges; the revision- precondition is the cross-replica backstop — a stale writer gets 412).+ precondition is the cross-replica backstop — a stale writer gets 409).No policy state is persisted server-side; reads reflect exactly what theegress enforces.@@ -160,12 +160,7 @@ def relay_put(service, sandbox_id: str, normalized: dict) -> dict:def relay_patch(service, sandbox_id: str, rules: list[NetworkRule]) -> dict:- """PATCH composed server-side: GET → merge → PUT(expectedRevision).-- The per-sandbox in-process lock serializes local merges; the revision- precondition inside the merged PUT is the cross-replica backstop (a- concurrent writer commits first and the stale PATCH sees 412).- """+ """PATCH composed server-side: GET → merge → PUT(expectedRevision)."""with service.policy_lock(sandbox_id):state = _relay_get_full(service, sandbox_id)merged = merge_policy_rules(state["policy"], rules)@@ -182,7 +177,7 @@ def relay_patch(service, sandbox_id: str, rules: list[NetworkRule]) -> dict:def relay_delete_rules(service, sandbox_id: str, targets: list[str]) -> dict:- """Remove rules by target (idempotent) through the relay."""+ """Remove rules by target (idempotent): GET → filter → PUT."""with service.policy_lock(sandbox_id):state = _relay_get_full(service, sandbox_id)kept = delete_policy_rules(state["policy"], targets)