Skip to content

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.go
index 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.go
index 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 main
import (
@@ -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 int64
fence 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 policyRelayDocument
if 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 err
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, 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, subj
return 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] = deny
s.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.go
index 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.go
index 07b6f78d0..a2d5c302c 100644
--- a/components/egress/fastsandbox_policy_snapshot.go
+++ b/components/egress/fastsandbox_policy_snapshot.go
@@ -46,21 +46,13 @@ 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.
+// 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.Sub
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 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.go
index 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 a
s.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 == fence
diff --git a/components/egress/fastsandbox_vault.go b/components/egress/fastsandbox_vault.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.py
index 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`` (the
per-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 the
egress 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)