Skip to content

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

feat(egress): seal-free template state carry (vault + policy) — issue #2312

高然aaf5d9e396cb
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.go
index a95bad755..bc062e15c 100644
--- a/components/egress/fastsandbox_actions.go
+++ b/components/egress/fastsandbox_actions.go
@@ -113,10 +113,11 @@ func (s *fastSandboxPolicyServer) handleActionsStatus(w http.ResponseWriter, r *
// 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: policyRecovery,
- DegradedPolicies: s.degradedPolicyUIDs(),
- DegradedVaults: degraded,
+ PolicyTransfer: s.policyFiles != nil,
+ PolicyRecovery: policyRecovery,
+ DegradedPolicies: s.degradedPolicyUIDs(),
+ DegradedVaults: degraded,
+ TemplateStateExport: true,
}
if s.mitmGate != nil {
resp.MitmCaFingerprint = s.mitmGate.CAFingerprint()
@@ -228,8 +229,14 @@ func (s *fastSandboxPolicyServer) applySetBinding(env *actionhandler.Envelope) (
// 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)
+ // Policy first: its reload result is the validation policy for the
+ // vault reload (a template clone's vault hosts are covered by the
+ // landed template policy, not by the replayed bootstrap input).
+ seed := s.rehydratePolicyReload(subj, fence)
+ if seed == nil {
+ seed = pol
+ }
+ s.rehydrateVaultReload(subj, fence, seed)
}
state, err := s.reg.RegisterAndEnforce(subj, subject.SubjectKey{SourceIP: att.IP}, fence, func() error {
return s.OnRegistered(subj, att)
diff --git a/components/egress/fastsandbox_policy_persist.go b/components/egress/fastsandbox_policy_persist.go
index 9e1c1cc79..3bffea0e1 100644
--- a/components/egress/fastsandbox_policy_persist.go
+++ b/components/egress/fastsandbox_policy_persist.go
@@ -21,6 +21,11 @@
// 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.
+//
+// TODO(encryption-at-rest): template-borne state blobs are stored as-is.
+// When encryption lands it protects the store-side reader only — CLONE
+// ISOLATION is determined by KEY SCOPING (per-tenant/pool keys), so design
+// the key hierarchy with the template-distribution flow in mind.
package main
import (
@@ -370,24 +375,27 @@ func (s *fastSandboxPolicyServer) clearPolicyRecordLocked(subj subject.Subject)
// 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) {
+// Returns the policy the subject must run per the reload: the file-backed
+// policy, default-deny when degraded, or nil when the binding input seeds
+// (fresh subject).
+func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fence subject.Fencing) *policy.NetworkPolicy {
s.mu.Lock()
defer s.mu.Unlock()
if e := s.policies[subj]; e != nil {
if e.fence == fence {
- return
+ return nil
}
delete(s.policies, subj)
}
fs, err := s.policyFiles.storeFor(subj)
if err != nil {
s.degradePolicyReloadLocked(subj, fence, fmt.Sprintf("policy file store unavailable: %v", err))
- return
+ return policy.DefaultDenyPolicy()
}
snap, err := fs.Snapshot()
if err != nil {
s.degradePolicyReloadLocked(subj, fence, fmt.Sprintf("policy file unreadable: %v", err))
- return
+ return policy.DefaultDenyPolicy()
}
if !snap.Exists() {
// Fresh subject: the binding input seeds. A durable seal marker (an
@@ -397,9 +405,9 @@ func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fe
s.policies[subj] = &policyEntry{fence: fence, sealed: true}
s.pendingPolicies[subj] = policy.DefaultDenyPolicy()
log.Infof("subject %s: seal restored from marker (file-less subject)", subj)
- return
+ return policy.DefaultDenyPolicy()
}
- return
+ return nil
}
pf, body, decErr := policy.DecodePolicyFile(snap.Data())
if decErr != nil {
@@ -414,7 +422,7 @@ func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fe
}
}
s.degradePolicyReloadLocked(subj, fence, fmt.Sprintf("policy file unusable (%v)", decErr))
- return
+ return policy.DefaultDenyPolicy()
}
recorded := subject.Fencing{RuntimeInstanceID: pf.Incarnation, AttachmentID: pf.AttachmentID}
if !recorded.Matches(fence) {
@@ -425,17 +433,17 @@ func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fe
} else {
log.Infof("subject %s: stale policy file discarded (fence %s/%s ≠ %s/%s)", subj, pf.Incarnation, pf.AttachmentID, fence.RuntimeInstanceID, fence.AttachmentID)
}
- return
+ return nil
}
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)
s.degradePolicyReloadLocked(subj, fence, fmt.Sprintf("policy file quarantine failed: %v", delErr))
- return
+ return policy.DefaultDenyPolicy()
}
s.degradePolicyReloadLocked(subj, fence, fmt.Sprintf("policy file content rejected (%v)", parseErr))
- return
+ return policy.DefaultDenyPolicy()
}
entry := &policyEntry{revision: pf.Revision, fence: fence}
// A durable seal marker (export acked, teardown not yet delivered)
@@ -448,6 +456,7 @@ func (s *fastSandboxPolicyServer) rehydratePolicyReload(subj subject.Subject, fe
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)
+ return pol
}
// applyBindingPolicyLocked seeds the binding's policy for a freshly
diff --git a/components/egress/fastsandbox_policy_persist_test.go b/components/egress/fastsandbox_policy_persist_test.go
index 937e3e9fc..7004ae9dc 100644
--- a/components/egress/fastsandbox_policy_persist_test.go
+++ b/components/egress/fastsandbox_policy_persist_test.go
@@ -19,6 +19,7 @@ import (
"errors"
"fmt"
"net/http"
+ "net/http/httptest"
"os"
"path/filepath"
"testing"
@@ -65,6 +66,15 @@ func newPolicyPersistHarness(t *testing.T) *policyPersistHarness {
}
h.pp = pp
h.srv.SetPolicyFiles(pp)
+ // The policy clone flow also exercises the vault transfer (template
+ // carry exports both states), so the harness wires vault persistence as
+ // a SIBLING state directory (mirroring the production layout — same
+ // volume, distinct basenames; aliasing them would clobber the shared
+ // <uid>.json names).
+ vp, err := newVaultPersistence(filepath.Join(h.dir, "vault"))
+ require.NoError(t, err)
+ vp.newFile = pp.newFile
+ h.srv.SetVaultFiles(vp)
return h
}
@@ -133,7 +143,7 @@ func (h *policyPersistHarness) seedPolicyBundle(t *testing.T, path string, revis
}
// policySnapshotBody builds a POLICY_EXPORT / POLICY_IMPORT envelope.
-func policySnapshotBody(t *testing.T, uid, runtimeID, attID, op, path string) string {
+func policySnapshotBody(t *testing.T, uid, runtimeID, attID, op, path string, seal *bool) string {
t.Helper()
env := actionhandler.Envelope{
APIVersion: constants.ActionsAPIVersion,
@@ -146,7 +156,7 @@ func policySnapshotBody(t *testing.T, uid, runtimeID, attID, op, path string) st
AttachmentID: attID,
RouteGeneration: 1,
},
- Snapshot: &actionhandler.SnapshotTransfer{Path: path},
+ Snapshot: &actionhandler.SnapshotTransfer{Path: path, Seal: seal},
}
raw, err := json.Marshal(env)
require.NoError(t, err)
@@ -594,7 +604,7 @@ func TestPolicyPersistSealedFilelessSubjectSurvivesRestart(t *testing.T) {
require.Equal(t, http.StatusOK, rec.Code)
require.False(t, h.fileFor(policyTestUID).exists, "precondition: file-less after removal")
bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
- rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
h.srv.mu.Lock()
require.True(t, h.srv.policies[subject.FromSandboxUID(policyTestUID)].sealed)
@@ -631,6 +641,85 @@ func TestPolicyPersistSealedFilelessSubjectSurvivesRestart(t *testing.T) {
_ = reg2
}
+// TestTemplateCloneAdoptsPolicyAndVault (issue #2312 acceptance 2): the
+// template's policy and vault records are adopted at the clone's first
+// registration — re-stamped to the clone's fence, revision preserved, vault
+// validated against the LANDED template policy (not the bootstrap input),
+// and enforced in-guest.
+func TestTemplateCloneAdoptsPolicyAndVault(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+
+ // Template source: allow a.com + b.com, with a vault binding on a.com.
+ h.readySubject(t, "template-u", vaultTestIP)
+ rec := doPolicy(t, h.srv, http.MethodPut, "template-u", policyPutDoc(
+ `{"defaultAction":"deny","egress":[{"action":"allow","target":"a.com"},{"action":"allow","target":"api.example.com"}]}`, 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doVault(t, h.srv, http.MethodPost, "template-u", vaultCredential(), "")
+ require.Equal(t, http.StatusCreated, rec.Code)
+
+ // Template carry: seal-free exports of both states.
+ bundle := filepath.Join(t.TempDir(), "bundle")
+
+ require.NoError(t, os.MkdirAll(bundle, 0o700))
+ sealFree := false
+ rec = doAction(t, h.srv, policySnapshotBody(t, "template-u", testFenceR, testFenceA, "POLICY_EXPORT", filepath.Join(bundle, "policy.json"), &sealFree))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, policySnapshotBody(t, "template-u", testFenceR, testFenceA, "VAULT_EXPORT", filepath.Join(bundle, "vault.json"), &sealFree))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The source keeps full CRUD (seal-free).
+ rec = doPolicy(t, h.srv, http.MethodGet, "template-u", "", "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doVault(t, h.srv, http.MethodGet, "template-u", "", "")
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // The clone: fresh subject on a new fence; the driver hands both
+ // bundle files over strictly before SET_BINDING. The imports re-stamp
+ // the records to the clone's fence for the next registration.
+ const cloneUID, cloneIP = "clone-u", "10.9.2.5"
+ const cloneR, cloneA = "clone-runtime", "clone-attachment"
+ // Materialize the published bundle (the driver uploads the staged
+ // files; the restore side pulls them back to disk).
+ for _, name := range []string{"policy.json", "vault.json"} {
+ staged := h.fakeForPath(filepath.Join(bundle, name))
+ require.True(t, staged.exists, "the template export must have staged %s", name)
+ require.NoError(t, os.WriteFile(filepath.Join(bundle, name), staged.data, 0o600))
+ }
+ rec = doAction(t, h.srv, policySnapshotBody(t, cloneUID, cloneR, cloneA, "POLICY_IMPORT", filepath.Join(bundle, "policy.json"), nil))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, policySnapshotBody(t, cloneUID, cloneR, cloneA, "VAULT_IMPORT", filepath.Join(bundle, "vault.json"), nil))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // First registration: the bootstrap input (default-allow) is
+ // superseded by the landed template policy; the vault reload validates
+ // against that LANDED policy, so the clone adopts both.
+ rec = doAction(t, h.srv, bindBody(t, cloneUID, cloneIP, cloneR, cloneA, 1, strPtr(`{"defaultAction":"allow"}`)))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, cloneUID, cloneR, cloneA, constants.HookRuntimeReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doAction(t, h.srv, hookBody(t, cloneUID, cloneR, cloneA, constants.HookDataPlaneReady))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ clone := subject.FromSandboxUID(cloneUID)
+ assert.Equal(t, "allow", reg_UserEvaluate(h.srv, clone, "a.com"), "the template policy is enforced")
+ assert.Equal(t, "deny", reg_UserEvaluate(h.srv, clone, "c.com"))
+
+ // The clone's vault is live and injected from the adopted record.
+ req := httptest.NewRequest(http.MethodGet, "/credential-vault/_active?clientIp="+cloneIP, nil)
+ rec2 := httptest.NewRecorder()
+ h.srv.handleCredentialVaultActive(rec2, req)
+ require.Equal(t, http.StatusOK, rec2.Code)
+ assert.Contains(t, rec2.Body.String(), "Bearer sekret")
+
+ // The adopted record is authoritative over later binding replays.
+ rec = doAction(t, h.srv, bindBody(t, cloneUID, cloneIP, cloneR, cloneA, 2, strPtr(`{"defaultAction":"allow"}`)))
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doPolicy(t, h.srv, http.MethodGet, cloneUID, "", "")
+ rev, doc := mustPolicyRevision(t, rec)
+ assert.Equal(t, int64(2), rev, "the landed revision is preserved through adoption")
+ assert.Contains(t, string(doc.Policy), "a.com")
+}
+
// ---------------------------------------------------------------------------
// Capability + healthy posture
// ---------------------------------------------------------------------------
@@ -645,6 +734,7 @@ func TestPolicyPersistCapabilityFlag(t *testing.T) {
srv, _, _ := fastSandboxTestServer(t)
status = mustStatus(t, srv)
assert.True(t, status.PolicyTransfer)
+ assert.True(t, status.TemplateStateExport, "seal-free template carry + land-for-next-registration are supported")
assert.NotContains(t, mustStatusBodyJSON(t, srv), "policyRecovery", "healthy posture omits the recovery flag")
}
diff --git a/components/egress/fastsandbox_policy_snapshot.go b/components/egress/fastsandbox_policy_snapshot.go
index a2d5c302c..cb1f86295 100644
--- a/components/egress/fastsandbox_policy_snapshot.go
+++ b/components/egress/fastsandbox_policy_snapshot.go
@@ -75,8 +75,7 @@ func (s *fastSandboxPolicyServer) applyPolicyExport(env *actionhandler.Envelope)
// Phase 1: guards + consistent source image, serialized with the policy
// relay commits (policyCommitMu). A relay writer that passed its guards
// but has not committed yet is either flushed before the snapshot (the
- // copy carries its write) or blocked until phase 3 — it can never
- // commit "under" the seal.
+ // copy carries its write) or blocked until phase 3.
s.policyCommitMu.Lock()
s.mu.Lock()
snap, status, err := s.policyExportSourceImageLocked(subj, fence, regFence, registered)
@@ -130,6 +129,16 @@ func (s *fastSandboxPolicyServer) applyPolicyExport(env *actionhandler.Envelope)
return http.StatusInternalServerError, fmt.Errorf("policy bundle removal failed (state %v): %v", state, err)
}
}
+ // Seal-free template carry: the record was copied verbatim and the
+ // source keeps full relay CRUD — no latch, bookkeeping untouched.
+ if !env.Snapshot.Sealed() {
+ if snap.Exists() {
+ log.Infof("subject %s: policy exported to snapshot bundle, seal-free (template carry)", subj)
+ } else {
+ log.Infof("subject %s: no policy file to export, seal-free (template carry)", subj)
+ }
+ return http.StatusOK, nil
+ }
// 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 {
diff --git a/components/egress/fastsandbox_policy_snapshot_test.go b/components/egress/fastsandbox_policy_snapshot_test.go
index d7bc9c84f..e8f9157f7 100644
--- a/components/egress/fastsandbox_policy_snapshot_test.go
+++ b/components/egress/fastsandbox_policy_snapshot_test.go
@@ -44,7 +44,7 @@ func TestPolicySnapshotExportCopiesAndSeals(t *testing.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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
// The bundle copy is byte-identical to the subject's policy file.
@@ -65,7 +65,7 @@ func TestPolicySnapshotExportCopiesAndSeals(t *testing.T) {
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))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
assert.Equal(t, policyFile.data, h.fakeForPath(bundlePath).data)
}
@@ -82,7 +82,7 @@ func TestPolicySnapshotExportWithoutPolicyFileStillSeals(t *testing.T) {
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))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
assert.False(t, h.fakeForPath(bundlePath).exists, "nothing to carry: no policy file, no bundle write")
}
@@ -92,7 +92,7 @@ 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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, "unregistered-sandbox", testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
assert.False(t, h.fakeForPath(bundlePath).exists, "nothing to carry: no subject, no bundle write")
}
@@ -101,7 +101,7 @@ func TestPolicySnapshotExportGuards(t *testing.T) {
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"))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, "old-runtime", testFenceA, "POLICY_EXPORT", "/tmp/bundle.json", nil))
assert.Equal(t, http.StatusConflict, rec.Code)
h.srv.mu.Lock()
e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
@@ -114,7 +114,7 @@ func TestPolicySnapshotExportGuards(t *testing.T) {
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
h.srv.mu.Lock()
e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
@@ -127,7 +127,7 @@ func TestPolicySnapshotExportGuards(t *testing.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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", inside, nil))
assert.Equal(t, http.StatusBadRequest, rec.Code)
h.srv.mu.Lock()
e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
@@ -151,7 +151,7 @@ func TestPolicySnapshotExportGuards(t *testing.T) {
f.exists = true
}
- rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
assert.Equal(t, http.StatusConflict, rec.Code)
h.srv.mu.Lock()
e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
@@ -161,6 +161,35 @@ func TestPolicySnapshotExportGuards(t *testing.T) {
})
}
+// TestPolicySnapshotExportSealFree (issue #2312, Seal=false): the template
+// carry copies the record verbatim and the source keeps full relay CRUD —
+// no seal latch, revision bookkeeping unchanged.
+func TestPolicySnapshotExportSealFree(t *testing.T) {
+ h := newPolicyPersistHarness(t)
+ h.readySubject(t, policyTestUID, vaultTestIP)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", policyTestUID+".json")
+ sealFree := false
+
+ before := h.fakeForPath(filepath.Join(h.dir, policyTestUID+".json")).data
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, &sealFree))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ // Byte-identical copy of the persisted record.
+ bundle := h.fakeForPath(bundlePath)
+ require.True(t, bundle.exists)
+ assert.Equal(t, before, bundle.data)
+
+ // The source keeps full relay CRUD — no 409, no seal latch.
+ 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")
+ rec = doPolicy(t, h.srv, http.MethodPut, policyTestUID, policyPutDoc(policyAllowAlt(), 1, false, true), "")
+ require.Equal(t, http.StatusOK, rec.Code, "the source keeps CRUD after a seal-free export")
+ rec = doPolicy(t, h.srv, http.MethodDelete, policyTestUID, "", "")
+ assert.Equal(t, http.StatusNoContent, rec.Code)
+}
+
// ---------------------------------------------------------------------------
// Import: re-stamp + commit protocol
// ---------------------------------------------------------------------------
@@ -172,7 +201,7 @@ func TestPolicySnapshotImportLandsFileBeforeRegistration(t *testing.T) {
// 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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
// Landed via the commit protocol, re-stamped with the restored fence —
@@ -219,7 +248,7 @@ func TestPolicySnapshotImportAfterSetBindingInstallsAndUnseals(t *testing.T) {
// 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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
h.srv.mu.Lock()
e := h.srv.policies[subject.FromSandboxUID(policyTestUID)]
@@ -229,7 +258,7 @@ func TestPolicySnapshotImportAfterSetBindingInstallsAndUnseals(t *testing.T) {
// 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))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_IMPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
// The imported policy is live and unsealed.
@@ -256,14 +285,14 @@ func TestPolicySnapshotImportRejects(t *testing.T) {
}
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
assert.Equal(t, http.StatusBadRequest, rec.Code)
})
t.Run("invalid policy content", func(t *testing.T) {
@@ -272,34 +301,34 @@ func TestPolicySnapshotImportRejects(t *testing.T) {
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", inside, nil))
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
assert.Equal(t, http.StatusServiceUnavailable, rec.Code)
assert.False(t, h.fileFor(policyTestUID).exists, "no policy file mutation while latched")
})
@@ -313,7 +342,7 @@ func TestPolicySnapshotDuplicateImportDoesNotRollBack(t *testing.T) {
// 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))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
// Relay writes resume: revision 6 lands.
@@ -321,7 +350,7 @@ func TestPolicySnapshotDuplicateImportDoesNotRollBack(t *testing.T) {
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))
+ rec = doAction(t, h.srv, policySnapshotBody(t, policyTestUID, snapshotResumeR, snapshotResumeA, "POLICY_IMPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
pf, _ := decodePolicyFile(t, h.fileFor(policyTestUID))
@@ -340,7 +369,7 @@ func TestPolicySnapshotRemoveBindingPurgesSealed(t *testing.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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
require.True(t, h.fakeForPath(bundlePath).exists, "precondition: the bundle copy is intact")
@@ -380,7 +409,7 @@ func TestPolicySnapshotSealSurvivesRestart(t *testing.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))
+ rec := doAction(t, h.srv, policySnapshotBody(t, policyTestUID, testFenceR, testFenceA, "POLICY_EXPORT", bundlePath, nil))
require.Equal(t, http.StatusOK, rec.Code)
// Fresh server over the same persistence state + binding replay.
diff --git a/components/egress/fastsandbox_vault_persist.go b/components/egress/fastsandbox_vault_persist.go
index a0e984371..ff2fa5e97 100644
--- a/components/egress/fastsandbox_vault_persist.go
+++ b/components/egress/fastsandbox_vault_persist.go
@@ -14,7 +14,12 @@
// Egress-held vault persistence (OSEP-0022 stage 2): one file per subject
// under <egress-volume>/vault/, so an egress restart recovers locally — no
-// server re-push exists or is needed. Ordering is persist → apply → ack
+// server re-push exists or is needed.
+//
+// TODO(encryption-at-rest): template-borne vault blobs are stored as-is.
+// When encryption lands it protects the store-side reader only — CLONE
+// ISOLATION is determined by KEY SCOPING (per-tenant/pool keys), so design
+// the key hierarchy with the template-distribution flow in mind. Ordering is persist → apply → ack
// (acked ⇒ durable and applied), reusing the policy-persistence machinery's
// three-state classification, snapshot restore, and recovery latch.
package main
diff --git a/components/egress/fastsandbox_vault_snapshot.go b/components/egress/fastsandbox_vault_snapshot.go
index e75282c13..5f8f5c2da 100644
--- a/components/egress/fastsandbox_vault_snapshot.go
+++ b/components/egress/fastsandbox_vault_snapshot.go
@@ -67,7 +67,11 @@ func reservesPathUnder(dir, path string) bool {
}
// applyVaultExport copies the subject's vault file into the bundle target and
-// marks the subject sealed. A subject without a vault file just seals. Any
+// marks the subject sealed (SnapshotTransfer.Seal absent/true — the
+// checkpoint flow); Seal=false is the seal-free template carry: the record
+// is copied verbatim and the source keeps full relay CRUD. A subject
+// without a vault file just seals (checkpoint) / exports nothing
+// (template). Any
// failure leaves the subject unsealed and active; 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
@@ -148,6 +152,19 @@ func (s *fastSandboxPolicyServer) applyVaultExport(env *actionhandler.Envelope)
return http.StatusInternalServerError, fmt.Errorf("vault bundle removal failed (state %v): %v", state, err)
}
}
+ // Seal-free template carry: the record was copied verbatim and the
+ // source keeps full relay CRUD — no latch, bookkeeping untouched. (The
+ // vault blob is carried as-is; encryption at rest is a deferred TODO in
+ // the vault persist layer, and clone isolation is key scoping, not the
+ // blob.)
+ if !env.Snapshot.Sealed() {
+ if snap.Exists() {
+ log.Infof("subject %s: vault exported to snapshot bundle, seal-free (template carry)", subj)
+ } else {
+ log.Infof("subject %s: no vault file to export, seal-free (template carry)", subj)
+ }
+ return http.StatusOK, nil
+ }
// Durable seal first: a restart before REMOVE_BINDING must reload the
// entry sealed, or relay writes would stale the taken bundle.
if err := s.vaultFiles.seal(subj); err != nil {
diff --git a/components/egress/fastsandbox_vault_snapshot_test.go b/components/egress/fastsandbox_vault_snapshot_test.go
index 96bedf99d..15f37df27 100644
--- a/components/egress/fastsandbox_vault_snapshot_test.go
+++ b/components/egress/fastsandbox_vault_snapshot_test.go
@@ -44,7 +44,7 @@ const (
)
// snapshotBody builds a VAULT_EXPORT / VAULT_IMPORT envelope.
-func snapshotBody(t *testing.T, uid, runtimeID, attID, op, path string) string {
+func snapshotBody(t *testing.T, uid, runtimeID, attID, op, path string, seal ...*bool) string {
t.Helper()
env := actionhandler.Envelope{
APIVersion: constants.ActionsAPIVersion,
@@ -59,6 +59,9 @@ func snapshotBody(t *testing.T, uid, runtimeID, attID, op, path string) string {
},
Snapshot: &actionhandler.SnapshotTransfer{Path: path},
}
+ if len(seal) > 0 {
+ env.Snapshot.Seal = seal[0]
+ }
raw, err := json.Marshal(env)
require.NoError(t, err)
return string(raw)
@@ -267,6 +270,32 @@ func TestVaultSnapshotExportGuards(t *testing.T) {
})
}
+// TestVaultSnapshotExportSealFree (issue #2312, Seal=false): the template
+// carry copies the vault file verbatim and the source keeps full relay CRUD.
+func TestVaultSnapshotExportSealFree(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ h.snapshotSubject(t)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", snapshotTestUID+".json")
+ sealFree := false
+
+ before := h.fileFor(snapshotTestUID).data
+ rec := doAction(t, h.srv, snapshotBody(t, snapshotTestUID, testFenceR, testFenceA, "VAULT_EXPORT", bundlePath, &sealFree))
+ require.Equal(t, http.StatusOK, rec.Code)
+
+ bundle := h.fakeForPath(bundlePath)
+ require.True(t, bundle.exists)
+ assert.Equal(t, before, bundle.data, "byte-identical copy")
+
+ // The source keeps full relay CRUD (no seal): GET works, a relay write
+ // lands, and the write does not leak into the taken bundle.
+ rec = doVault(t, h.srv, http.MethodGet, snapshotTestUID, "", "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ rec = doVault(t, h.srv, http.MethodPut, snapshotTestUID, vaultPut("1"), "")
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.NotEqual(t, before, h.fileFor(snapshotTestUID).data, "the source moved on")
+ assert.Equal(t, before, bundle.data, "the taken bundle is unchanged")
+}
+
// ---------------------------------------------------------------------------
// Import: re-stamp + commit protocol
// ---------------------------------------------------------------------------
diff --git a/components/egress/pkg/actionhandler/actionhandler.go b/components/egress/pkg/actionhandler/actionhandler.go
index 92d2f6743..257cf2e6f 100644
--- a/components/egress/pkg/actionhandler/actionhandler.go
+++ b/components/egress/pkg/actionhandler/actionhandler.go
@@ -114,9 +114,23 @@ type Hook struct {
}
// SnapshotTransfer names the driver-provided staging file for one subject's
-// vault snapshot: the export target, or the bundle source at restore.
+// state snapshot (vault / recorded policy): the export target, or the bundle
+// source at restore.
type SnapshotTransfer struct {
Path string `json:"path"`
+ // Seal selects the export semantics. Absent/nil = sealed (the
+ // checkpoint flow: the subject is locked out of the copied state until
+ // an import or teardown re-owns it). Seal=false = seal-free carry —
+ // the record is copied verbatim and the source keeps full relay CRUD
+ // (the template flow: the source stays live and the clone adopts the
+ // carried state at its first registration).
+ Seal *bool `json:"seal,omitempty"`
+}
+
+// Sealed reports the export semantics: nil means the checkpoint default
+// (sealed).
+func (t *SnapshotTransfer) Sealed() bool {
+ return t.Seal == nil || *t.Seal
}
// validatePath enforces the Pod-local absolute-path contract at parse time,
@@ -306,4 +320,11 @@ type StatusResponse struct {
// closed for them; a relay write heals).
PolicyRecovery bool `json:"policyRecovery,omitempty"`
DegradedPolicies []string `json:"degradedPolicies,omitempty"`
+ // TemplateStateExport reports that this Handler supports the
+ // seal-free template state carry (SnapshotTransfer.Seal=false exports
+ // keep the source live; imports land for the next registration).
+ // Absent on older builds decodes as false: the Fastlet's template
+ // snapshots then export nothing (handlers that always seal are never
+ // asked) — rolling upgrades are safe in both directions.
+ TemplateStateExport bool `json:"templateStateExport,omitempty"`
}