Skip to content

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

fix(egress): fail closed on Vault v2 state writes

leo peineacf8176dae0
diff --git a/components/egress/fastsandbox_actions.go b/components/egress/fastsandbox_actions.go
index 433daf590..c411c55a8 100644
--- a/components/egress/fastsandbox_actions.go
+++ b/components/egress/fastsandbox_actions.go
@@ -214,6 +214,14 @@ func (s *fastSandboxPolicyServer) applySetBinding(ctx context.Context, env *acti
defer s.policyCommitMu.Unlock()
old, registered := s.reg.Fence(subj)
oldState, _ := s.reg.Get(subj)
+ if stale, ok := s.reg.Resolve(subject.SubjectKey{SourceIP: att.IP}); ok && stale != subj {
+ s.mu.Lock()
+ status, purgeErr := s.vaultPurgeStatusLocked(stale)
+ s.mu.Unlock()
+ if purgeErr != nil {
+ return status, fmt.Errorf("stale subject cleanup blocked: %w", purgeErr)
+ }
+ }
s.mu.Lock()
// Waiting for an in-progress Vault commit may outlive the request too.
if err := s.actionCanceled(ctx); err != nil {
@@ -237,6 +245,14 @@ func (s *fastSandboxPolicyServer) applySetBinding(ctx context.Context, env *acti
return http.StatusInternalServerError, fmt.Errorf("active subject %s has no registered network", subj)
}
}
+ willPurge := token != nil && (!token.expectedNew.Matches(fence) || !token.purged) || token == nil && registered && !old.Matches(fence)
+ if willPurge {
+ status, purgeErr := s.vaultPurgeStatusLocked(subj)
+ if purgeErr != nil {
+ s.mu.Unlock()
+ return status, fmt.Errorf("subject rebind blocked: %w", purgeErr)
+ }
+ }
// A null binding may omit attachment only for its own known identity.
// Never register a new fence using the previous instance's network.
if env.Binding.IsRemoval() && env.Attachment == nil {
@@ -274,7 +290,11 @@ func (s *fastSandboxPolicyServer) applySetBinding(ctx context.Context, env *acti
}
s.reg.Unregister(subj)
s.mu.Lock()
- s.dropSubjectStateLocked(subj) // preserve this exact token through C publication
+ if err := s.dropSubjectStateLocked(subj); err != nil { // preserve this exact token through C publication
+ status := s.vaultPurgeFailureStatusLocked(subj)
+ s.mu.Unlock()
+ return status, fmt.Errorf("subject reset purge: %w", err)
+ }
token.needsReset = false
token.oldRemoved = true
token.purged = true
@@ -282,7 +302,11 @@ func (s *fastSandboxPolicyServer) applySetBinding(ctx context.Context, env *acti
}
s.mu.Lock()
if !token.purged {
- s.dropSubjectStateLocked(subj)
+ if err := s.dropSubjectStateLocked(subj); err != nil {
+ status := s.vaultPurgeFailureStatusLocked(subj)
+ s.mu.Unlock()
+ return status, fmt.Errorf("subject rebind purge: %w", err)
+ }
token.purged = true
}
removeOld := token.removeOld && !token.oldRemoved
@@ -477,8 +501,16 @@ func (s *fastSandboxPolicyServer) applyRemoveBinding(env *actionhandler.Envelope
log.Infof("subject %s: stale REMOVE_BINDING ignored (fence mismatch)", subj)
return http.StatusOK, nil
}
+ s.mu.Lock()
+ purgeStatus, purgeErr := s.vaultPurgeStatusLocked(subj)
+ s.mu.Unlock()
+ if purgeErr != nil {
+ return purgeStatus, fmt.Errorf("binding removal blocked: %w", purgeErr)
+ }
if token == nil && !ok {
+ s.policyCommitMu.Lock()
s.dropSubjectState(subj)
+ s.policyCommitMu.Unlock()
return http.StatusOK, nil
}
// expectedNew REMOVE cancels an unfinished registration intent, including
@@ -491,13 +523,20 @@ func (s *fastSandboxPolicyServer) applyRemoveBinding(env *actionhandler.Envelope
// Terminal file cleanup remains best-effort after Unregister. A failed
// delete leaves the file fenced to the old identity; this acknowledgement
// does not promise automatic cleanup retry.
+ s.policyCommitMu.Lock()
s.mu.Lock()
- s.dropSubjectStateLocked(subj)
+ if err := s.dropSubjectStateLocked(subj); err != nil {
+ status := s.vaultPurgeFailureStatusLocked(subj)
+ s.mu.Unlock()
+ s.policyCommitMu.Unlock()
+ return status, fmt.Errorf("terminal state purge: %w", err)
+ }
cleared := token != nil && s.rebinds[subj] == token
if cleared {
delete(s.rebinds, subj)
}
s.mu.Unlock()
+ s.policyCommitMu.Unlock()
if cleared {
log.Infof("subject_rebind_cleared")
}
diff --git a/components/egress/fastsandbox_server.go b/components/egress/fastsandbox_server.go
index e0db804c9..0682fbaed 100644
--- a/components/egress/fastsandbox_server.go
+++ b/components/egress/fastsandbox_server.go
@@ -418,10 +418,29 @@ func (s *fastSandboxPolicyServer) applyPolicy(subj subject.Subject, pol *policy.
// sealed marks a paused subject whose vault file was exported into the
// snapshot bundle: every vault op answers 409; enforcement is unchanged.
type vaultEntry struct {
- store *credentialvault.Store
- fence subject.Fencing
- degraded string
- sealed bool
+ store *credentialvault.Store
+ fence subject.Fencing
+ degraded string
+ sealed bool
+ fileMeta vaultFileMetadata
+ vaultStateUnknown bool
+ // vaultStateProtected records that this live fence previously observed a
+ // non-v1 source (v2 or an unsupported schema). A later missing/legacy file
+ // cannot erase that provenance and reopen the v1 writer path.
+ vaultStateProtected bool
+}
+
+// vaultFileMetadata keeps the complete decoded ordering/initialization
+// identity beside the read-only live slice. The source file remains the
+// durable authority; this metadata prevents a reload from silently dropping
+// lineage information even though OS-1 does not write v2 yet.
+type vaultFileMetadata struct {
+ version int
+ revision int64
+ state credentialvault.FileState
+ lineage string
+ stateRevision uint64
+ initializationID string
}
// vaultFor returns nil for absent or rebinding subjects. Otherwise the vault
@@ -594,7 +613,11 @@ func (s *fastSandboxPolicyServer) takeoverStaleSubject(stale subject.Subject) er
// The action gate prevents another registration from racing victim cleanup.
func (s *fastSandboxPolicyServer) dropSubjectState(subj subject.Subject) {
s.mu.Lock()
- s.dropSubjectStateLocked(subj)
+ if err := s.dropSubjectStateLocked(subj); err != nil {
+ s.mu.Unlock()
+ log.Warnf("subject %s: local state cleanup refused: %v", subj, err)
+ return
+ }
cleared := s.rebinds[subj] != nil
delete(s.rebinds, subj)
s.mu.Unlock()
@@ -607,13 +630,19 @@ func (s *fastSandboxPolicyServer) dropSubjectState(subj subject.Subject) {
// SETs use it only after full kernel removal and Unregister; Vault must stay
// guarded until the successor has completed local publication.
func (s *fastSandboxPolicyServer) dropSubjectStateLocked(subj subject.Subject) error {
- err := s.dropVault(subj)
+ if _, err := s.vaultPurgeStatusLocked(subj); err != nil {
+ return err
+ }
+ // v1 lifecycle cleanup is intentionally best-effort: a failed unlink is
+ // already logged by purgeVaultFile and the remaining bytes stay fenced to
+ // their recorded owner. v2/unknown schemas were refused by the preflight.
+ _ = s.dropVault(subj)
delete(s.policies, subj)
s.purgePolicyFile(subj)
delete(s.subjFence, subj)
delete(s.pendingPolicies, subj)
delete(s.subjAtt, subj)
- return err
+ return nil
}
// recordBindingState records a validated network attempt before enforcement.
diff --git a/components/egress/fastsandbox_vault.go b/components/egress/fastsandbox_vault.go
index 370d47349..60340a056 100644
--- a/components/egress/fastsandbox_vault.go
+++ b/components/egress/fastsandbox_vault.go
@@ -162,6 +162,16 @@ func (s *fastSandboxPolicyServer) handleVaultRelayWrite(w http.ResponseWriter, r
if store == nil {
return func() { http.Error(w, "unknown subject", http.StatusNotFound) }
}
+ if entry, ok := s.vaults[subj]; ok {
+ if entry.vaultStateUnknown {
+ return func() { http.Error(w, "vault state is unknown; refusing mutation", http.StatusServiceUnavailable) }
+ }
+ if entry.fileMeta.version >= credentialvault.VaultFileVersion2 {
+ return func() {
+ http.Error(w, "v2 vault state is read-only until lineage-aware writes are supported", http.StatusConflict)
+ }
+ }
+ }
pol := effective
var (
@@ -292,6 +302,9 @@ func (s *fastSandboxPolicyServer) readRelayVault(r *http.Request, subj subject.S
if s.vaultSealedLocked(subj) {
return credentialvault.FullRevision{}, http.StatusConflict, "subject vault is sealed (paused); the bundle copy is already taken", nil
}
+ if entry, ok := s.vaults[subj]; ok && entry.vaultStateUnknown {
+ return credentialvault.FullRevision{}, http.StatusServiceUnavailable, "vault state is unknown; refusing to treat it as absent", nil
+ }
store := s.vaultForLocked(subj, fence)
if store == nil {
return credentialvault.FullRevision{}, http.StatusNotFound, "unknown subject", nil
diff --git a/components/egress/fastsandbox_vault_persist.go b/components/egress/fastsandbox_vault_persist.go
index 6b8d867a7..1ee477798 100644
--- a/components/egress/fastsandbox_vault_persist.go
+++ b/components/egress/fastsandbox_vault_persist.go
@@ -28,6 +28,7 @@ import (
"errors"
"fmt"
"io/fs"
+ "net/http"
"os"
"path/filepath"
"sort"
@@ -329,6 +330,55 @@ func (s *fastSandboxPolicyServer) purgeVaultFile(subj subject.Subject) error {
return err
}
+// vaultPurgeStatusLocked protects the remaining lifecycle writer: unlike
+// relay/snapshot handlers, terminal REMOVE and rebind cleanup delete the file.
+// Callers hold s.mu and the action/commit gate before invoking it.
+func (s *fastSandboxPolicyServer) vaultPurgeStatusLocked(subj subject.Subject) (int, error) {
+ if entry, ok := s.vaults[subj]; ok {
+ if entry.vaultStateUnknown {
+ return http.StatusServiceUnavailable, errors.New("vault state is unknown; refusing lifecycle purge")
+ }
+ if entry.fileMeta.version >= credentialvault.VaultFileVersion2 {
+ return http.StatusConflict, errors.New("v2 vault state is read-only until lineage-aware lifecycle writes are supported")
+ }
+ }
+ if s.vaultFiles == nil {
+ return 0, nil
+ }
+ fileStore, err := s.vaultFiles.storeFor(subj)
+ if err != nil {
+ return http.StatusServiceUnavailable, fmt.Errorf("vault purge state unavailable: %w", err)
+ }
+ snapshot, err := fileStore.Snapshot()
+ if err != nil {
+ return http.StatusServiceUnavailable, fmt.Errorf("vault purge snapshot unavailable: %w", err)
+ }
+ if !snapshot.Exists() {
+ return 0, nil
+ }
+ vf, _, decodeErr := credentialvault.DecodeVaultFile(snapshot.Data())
+ if errors.Is(decodeErr, credentialvault.ErrUnsupportedFileVersion) {
+ return http.StatusServiceUnavailable, errors.New("vault file schema is unknown; refusing lifecycle purge")
+ }
+ if decodeErr == nil && vf.Version >= credentialvault.VaultFileVersion2 {
+ return http.StatusConflict, errors.New("v2 vault state is read-only until lineage-aware lifecycle writes are supported")
+ }
+ // Corrupt v1 files retain the pre-existing terminal cleanup behavior. A
+ // recognized v2/unknown schema is never deleted through this v1 path.
+ return 0, nil
+}
+
+// vaultPurgeFailureStatusLocked preserves a specific v2/unknown refusal. If a
+// transient preflight snapshot error clears during this recheck, status 0 must
+// still become a valid retryable HTTP error for the failed preflight.
+func (s *fastSandboxPolicyServer) vaultPurgeFailureStatusLocked(subj subject.Subject) int {
+ status, _ := s.vaultPurgeStatusLocked(subj)
+ if status < 100 || status > 599 {
+ return http.StatusInternalServerError
+ }
+ return status
+}
+
// persistVaultCandidateLocked runs the commit protocol; callers hold s.mu for
// the whole operation, which serializes per-subject writers. persist performs
// the durable effect and returns its three-state classification; apply
@@ -482,16 +532,26 @@ func (s *fastSandboxPolicyServer) rehydrateVaultReload(subj subject.Subject, fen
}
s.mu.Lock()
defer s.mu.Unlock()
+ protectedBefore := false
+ previousMeta := vaultFileMetadata{}
if e, live := s.vaults[subj]; live {
- if e.fence == fence {
+ if e.fence == fence && !e.vaultStateUnknown {
return
}
+ if e.fence == fence {
+ protectedBefore = e.vaultStateProtected
+ previousMeta = e.fileMeta
+ }
delete(s.vaults, subj)
}
- entry := vaultEntry{store: credentialvault.NewStore(nil, func() bool { return true }), fence: fence}
+ entry := vaultEntry{
+ store: credentialvault.NewStore(nil, func() bool { return true }), fence: fence,
+ fileMeta: previousMeta, vaultStateProtected: protectedBefore,
+ }
fs, err := s.vaultFiles.storeFor(subj)
if err != nil {
entry.degraded = fmt.Sprintf("vault file store unavailable: %v", err)
+ entry.vaultStateUnknown = true
s.vaults[subj] = entry
log.Warnf("subject %s: %s", subj, entry.degraded)
return
@@ -500,15 +560,41 @@ func (s *fastSandboxPolicyServer) rehydrateVaultReload(subj subject.Subject, fen
switch {
case err != nil:
entry.degraded = fmt.Sprintf("vault file unreadable: %v", err)
+ entry.vaultStateUnknown = true
log.Warnf("subject %s: %s", subj, entry.degraded)
case !snap.Exists():
- // Fresh subject: nothing persisted, nothing to recover.
+ if entry.vaultStateProtected {
+ // A previously observed v2/unsupported file disappearing is not
+ // evidence of a fresh v1 subject. Keep its provenance sticky for
+ // this fence so a relay write cannot replace it with v1.
+ entry.degraded = "previously protected vault state disappeared; refusing legacy fallback"
+ entry.vaultStateUnknown = true
+ log.Warnf("subject %s: %s", subj, entry.degraded)
+ }
+ // Otherwise a fresh subject has nothing persisted to recover.
default:
vf, body, decErr := credentialvault.DecodeVaultFile(snap.Data())
+ unsupported := errors.Is(decErr, credentialvault.ErrUnsupportedFileVersion)
+ if vf.Version >= credentialvault.VaultFileVersion2 || unsupported {
+ entry.vaultStateProtected = true
+ }
+ legacyDowngrade := protectedBefore && vf.Version < credentialvault.VaultFileVersion2 && !unsupported
+ if !legacyDowngrade {
+ entry.fileMeta = vaultFileMetadata{
+ version: vf.Version, revision: vf.Revision, state: vf.State, lineage: vf.StateLineage,
+ stateRevision: vf.StateRevision, initializationID: vf.InitializationID,
+ }
+ }
switch {
+ case legacyDowngrade:
+ entry.degraded = "previously protected vault state was replaced by a legacy file; refusing downgrade"
+ entry.vaultStateUnknown = true
+ log.Warnf("subject %s: %s", subj, entry.degraded)
case decErr != nil && errors.Is(decErr, credentialvault.ErrUnsupportedFileVersion):
- // Written by a newer consumer — reject without destroying.
+ // A newer or unreadable v2 state must remain available for a
+ // compatible reader; never quarantine or expose it as absent.
entry.degraded = fmt.Sprintf("vault file version not readable by this egress: %v", decErr)
+ entry.vaultStateUnknown = true
log.Warnf("subject %s: %s (file preserved for the newer writer)", subj, entry.degraded)
case decErr != nil:
// Structurally corrupt: quarantine so the degradation cannot
@@ -523,6 +609,13 @@ func (s *fastSandboxPolicyServer) rehydrateVaultReload(subj subject.Subject, fen
// WITHOUT quarantining the file — a policy/vault relay write
// heals the slice.
entry.degraded = "held degraded: the recorded policy is degraded at this restart"
+ entry.vaultStateUnknown = vf.Version >= credentialvault.VaultFileVersion2
+ log.Warnf("subject %s: %s (file kept)", subj, entry.degraded)
+ case vf.Version == credentialvault.VaultFileVersion2 && vf.State == credentialvault.FileStateEmpty:
+ // Empty is an explicit initialization decision, not a legacy
+ // absence. This stage cannot verify its mode/owner contract.
+ entry.degraded = "explicit empty vault state requires the strict mode protocol"
+ entry.vaultStateUnknown = true
log.Warnf("subject %s: %s (file kept)", subj, entry.degraded)
case (subject.Fencing{RuntimeInstanceID: vf.Incarnation, AttachmentID: vf.AttachmentID}).Matches(fence):
// Same-instance recovery: revalidate against the replayed binding
@@ -534,19 +627,33 @@ func (s *fastSandboxPolicyServer) rehydrateVaultReload(subj subject.Subject, fen
// quarantining here would silently destroy persisted
// credentials. A policy/vault relay write heals the slice; a
// policy heal + restart revives it from the kept file.
- if err := entry.store.Reload(vf.Revision, credentialvault.CreateRequest(body), pol); err != nil {
+ if vf.Version == credentialvault.VaultFileVersion2 && vf.State == credentialvault.FileStateDeleted {
+ // The persisted tombstone is known absence. Keep the store
+ // empty so the public GET remains 404, and keep the file as
+ // the source of truth until v2 writes are implemented.
+ log.Infof("subject %s: deleted v2 vault state reloaded (stateRevision %d)", subj, vf.StateRevision)
+ } else if err := entry.store.Reload(vf.Revision, credentialvault.CreateRequest(body), pol); err != nil {
entry.degraded = fmt.Sprintf("vault file reload rejected: %v", err)
+ entry.vaultStateUnknown = vf.Version >= credentialvault.VaultFileVersion2
log.Warnf("subject %s: %s (file kept; a policy/vault relay write heals the slice)", subj, entry.degraded)
} else {
- log.Infof("subject %s: vault reloaded from file (revision %d, incarnation %s)", subj, vf.Revision, vf.Incarnation)
+ log.Infof("subject %s: vault reloaded from file (version %d, revision %d, incarnation %s)", subj, vf.Version, vf.Revision, vf.Incarnation)
}
default:
- // Stale: discard durably. A failed purge is harmless — the
- // recorded fence mismatches every later registration regardless.
- if _, delErr := fs.Delete(); delErr != nil {
- log.Warnf("subject %s: stale vault file purge failed (stays fenced out): %v", subj, delErr)
+ if vf.Version >= credentialvault.VaultFileVersion2 {
+ // A v2 file belongs to an unknown lineage/owner here. Preserve
+ // it and block relay reads/writes; this stage cannot safely
+ // infer a transfer or purge authorization from the file alone.
+ entry.degraded = "v2 vault file owner does not match the current runtime fence"
+ entry.vaultStateUnknown = true
+ log.Warnf("subject %s: %s (file preserved)", subj, entry.degraded)
} else {
- log.Infof("subject %s: stale vault file discarded (fence %s/%s ≠ %s/%s)", subj, vf.Incarnation, vf.AttachmentID, fence.RuntimeInstanceID, fence.AttachmentID)
+ // Legacy v1 stale cleanup retains its existing behavior.
+ if _, delErr := fs.Delete(); delErr != nil {
+ log.Warnf("subject %s: stale vault file purge failed (stays fenced out): %v", subj, delErr)
+ } else {
+ log.Infof("subject %s: stale vault file discarded (fence %s/%s ≠ %s/%s)", subj, vf.Incarnation, vf.AttachmentID, fence.RuntimeInstanceID, fence.AttachmentID)
+ }
}
}
}
diff --git a/components/egress/fastsandbox_vault_persist_linux_test.go b/components/egress/fastsandbox_vault_persist_linux_test.go
index e3047219d..5f7546b29 100644
--- a/components/egress/fastsandbox_vault_persist_linux_test.go
+++ b/components/egress/fastsandbox_vault_persist_linux_test.go
@@ -110,3 +110,38 @@ func TestVaultPersistenceRealFileEndToEnd(t *testing.T) {
_, err = os.Lstat(path)
assert.True(t, os.IsNotExist(err))
}
+
+func TestVaultV2ReloadUsesRealFileAndNeverDowngrades(t *testing.T) {
+ for _, state := range []credentialvault.FileState{credentialvault.FileStateActive, credentialvault.FileStateDeleted} {
+ t.Run(string(state), func(t *testing.T) {
+ dir := t.TempDir()
+ uid := vaultTestUID
+ revision := int64(7)
+ body := bundleVaultBody(t)
+ if state == credentialvault.FileStateDeleted {
+ revision = 0
+ body = emptyVaultFileBody()
+ }
+ raw := encodeVaultV2Fixture(t, state, revision, 12, "", body)
+ path := filepath.Join(dir, uid+".json")
+ require.NoError(t, os.WriteFile(path, raw, 0o600))
+
+ srv, _ := newRealVaultTestServer(t, dir)
+ require.Equal(t, http.StatusOK, doAction(t, srv, bindBody(t, uid, vaultTestIP, testFenceR, testFenceA, 1, vaultAllowPolicy())).Code)
+ require.Equal(t, http.StatusOK, doAction(t, srv, hookBody(t, uid, testFenceR, testFenceA, constants.HookRuntimeReady)).Code)
+ require.Equal(t, http.StatusOK, doAction(t, srv, hookBody(t, uid, testFenceR, testFenceA, constants.HookDataPlaneReady)).Code)
+
+ get := doVault(t, srv, http.MethodGet, uid, "", "")
+ if state == credentialvault.FileStateActive {
+ require.Equal(t, http.StatusOK, get.Code)
+ assert.Contains(t, get.Body.String(), `"revision":7`)
+ } else {
+ require.Equal(t, http.StatusNotFound, get.Code)
+ }
+ assert.Equal(t, http.StatusConflict, doVault(t, srv, http.MethodPost, uid, vaultCredential(), "").Code)
+ got, err := os.ReadFile(path)
+ require.NoError(t, err)
+ assert.Equal(t, raw, got, "real persisted v2 bytes survive reload and rejected mutation")
+ })
+ }
+}
diff --git a/components/egress/fastsandbox_vault_persist_test.go b/components/egress/fastsandbox_vault_persist_test.go
index 4522297d0..da8ebddfa 100644
--- a/components/egress/fastsandbox_vault_persist_test.go
+++ b/components/egress/fastsandbox_vault_persist_test.go
@@ -149,6 +149,7 @@ type vaultPersistHarness struct {
dir string
files map[string]*fakeVaultFile
mapMu sync.Mutex
+ newFileErr error
}
func newVaultPersistHarness(t *testing.T) *vaultPersistHarness {
@@ -169,6 +170,11 @@ func newTestVaultPersistence(t *testing.T, h *vaultPersistHarness) *vaultPersist
vp, err := newVaultPersistence(h.dir)
require.NoError(t, err)
vp.newFile = func(path string) (vaultFileStore, error) {
+ if h.newFileErr != nil {
+ err := h.newFileErr
+ h.newFileErr = nil
+ return nil, err
+ }
h.mapMu.Lock()
defer h.mapMu.Unlock()
f, ok := h.files[path]
diff --git a/components/egress/fastsandbox_vault_snapshot.go b/components/egress/fastsandbox_vault_snapshot.go
index 79dde79ef..75e91830a 100644
--- a/components/egress/fastsandbox_vault_snapshot.go
+++ b/components/egress/fastsandbox_vault_snapshot.go
@@ -205,6 +205,14 @@ func (s *fastSandboxPolicyServer) exportSourceImageLocked(subj subject.Subject,
if recovery := s.vaultRecovery.Load(); recovery != nil {
return nil, http.StatusServiceUnavailable, fmt.Errorf("vault persistence recovery required: %s", recovery.reason)
}
+ if entry, ok := s.vaults[subj]; ok {
+ if entry.vaultStateUnknown {
+ return nil, http.StatusServiceUnavailable, errors.New("vault state is unknown; refusing snapshot export")
+ }
+ if entry.fileMeta.version >= credentialvault.VaultFileVersion2 {
+ return nil, http.StatusConflict, errors.New("v2 vault state is read-only until lineage-aware restore is supported")
+ }
+ }
fs, err := s.vaultFiles.storeFor(subj)
if err != nil {
return nil, http.StatusInternalServerError, fmt.Errorf("vault file store unavailable: %w", err)
@@ -214,11 +222,17 @@ func (s *fastSandboxPolicyServer) exportSourceImageLocked(subj subject.Subject,
return nil, http.StatusInternalServerError, fmt.Errorf("vault file snapshot: %w", err)
}
if snap.Exists() {
- // Carry only bytes attributable to the registered fence: a leftover
- // from a previous incarnation (purge failed), a corrupt file, or a
- // newer schema is treated as absent — never exported, or import
- // would re-stamp foreign credentials as current.
+ // The current reader can expose v2 state read-only but cannot restore
+ // its ordering lineage. Refuse before copying, sealing, or deleting a
+ // stale bundle; treating it as absent would make a successful snapshot
+ // impossible to restore.
vf, _, decErr := credentialvault.DecodeVaultFile(snap.Data())
+ if errors.Is(decErr, credentialvault.ErrUnsupportedFileVersion) || (decErr == nil && vf.Version >= credentialvault.VaultFileVersion2) {
+ return nil, http.StatusConflict, fmt.Errorf("v2 or unknown vault state cannot be exported before lineage-aware restore is supported")
+ }
+ // Carry only bytes attributable to the registered fence: a leftover
+ // from a previous incarnation (purge failed) or a corrupt v1 file is
+ // treated as absent, preserving the legacy behavior.
if decErr != nil || vf.Incarnation != regFence.RuntimeInstanceID || vf.AttachmentID != regFence.AttachmentID {
what := "unattributable fence"
if errors.Is(decErr, credentialvault.ErrUnsupportedFileVersion) {
@@ -273,6 +287,9 @@ func (s *fastSandboxPolicyServer) applyVaultImport(env *actionhandler.Envelope)
if err != nil {
return http.StatusBadRequest, fmt.Errorf("invalid vault bundle file: %v", err)
}
+ if vf.Version != credentialvault.VaultFileVersion {
+ return http.StatusConflict, fmt.Errorf("v%d vault bundles are read-only until lineage-aware import is supported", vf.Version)
+ }
// The authorized incarnation transfer.
payload, err := credentialvault.EncodeVaultFile(fence.RuntimeInstanceID, fence.AttachmentID, vf.Revision, body)
if err != nil {
@@ -299,18 +316,37 @@ func (s *fastSandboxPolicyServer) applyVaultImport(env *actionhandler.Envelope)
if recovery := s.vaultRecovery.Load(); recovery != nil {
return http.StatusServiceUnavailable, fmt.Errorf("vault persistence recovery required: %s", recovery.reason)
}
+ if entry, ok := s.vaults[subj]; ok {
+ if entry.vaultStateUnknown {
+ return http.StatusServiceUnavailable, errors.New("vault state is unknown; refusing snapshot import")
+ }
+ if entry.fileMeta.version >= credentialvault.VaultFileVersion2 {
+ return http.StatusConflict, errors.New("v2 vault state is read-only until lineage-aware writes are supported")
+ }
+ }
// At-least-once delivery: never roll a newer local revision back. The
// guard requires the stored fence to match the envelope — a newer file
// under an old incarnation is stale local state the import must
// supersede, not ack.
- if fs, fsErr := s.vaultFiles.storeFor(subj); fsErr == nil {
- if cur, snapErr := fs.Snapshot(); snapErr == nil && cur.Exists() {
- if curVF, _, decErr := credentialvault.DecodeVaultFile(cur.Data()); decErr == nil &&
- curVF.Incarnation == fence.RuntimeInstanceID && curVF.AttachmentID == fence.AttachmentID &&
- curVF.Revision > vf.Revision {
- log.Infof("subject %s: vault import superseded (local revision %d > bundle revision %d), idempotent ack", subj, curVF.Revision, vf.Revision)
- return http.StatusOK, nil
- }
+ fileStore, fsErr := s.vaultFiles.storeFor(subj)
+ if fsErr != nil {
+ return http.StatusInternalServerError, fmt.Errorf("vault file store unavailable: %w", fsErr)
+ }
+ current, snapErr := fileStore.Snapshot()
+ if snapErr != nil {
+ return http.StatusInternalServerError, fmt.Errorf("vault file snapshot: %w", snapErr)
+ }
+ if current.Exists() {
+ curVF, _, decErr := credentialvault.DecodeVaultFile(current.Data())
+ if decErr != nil && errors.Is(decErr, credentialvault.ErrUnsupportedFileVersion) {
+ return http.StatusConflict, errors.New("local vault file uses an unsupported schema; refusing to overwrite it")
+ }
+ if decErr == nil && curVF.Version != credentialvault.VaultFileVersion {
+ return http.StatusConflict, errors.New("local v2 vault state is read-only until lineage-aware writes are supported")
+ }
+ if decErr == nil && curVF.Incarnation == fence.RuntimeInstanceID && curVF.AttachmentID == fence.AttachmentID && curVF.Revision > vf.Revision {
+ log.Infof("subject %s: vault import superseded (local revision %d > bundle revision %d), idempotent ack", subj, curVF.Revision, vf.Revision)
+ return http.StatusOK, nil
}
}
// Commit-time fence re-validation against our own record (subjFence —
diff --git a/components/egress/fastsandbox_vault_v2_compat_test.go b/components/egress/fastsandbox_vault_v2_compat_test.go
new file mode 100644
index 000000000..6214ba8e7
--- /dev/null
+++ b/components/egress/fastsandbox_vault_v2_compat_test.go
@@ -0,0 +1,488 @@
+// Copyright 2026 The OpenSandbox Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+ "encoding/json"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/alibaba/opensandbox/egress/pkg/credentialvault"
+ "github.com/alibaba/opensandbox/egress/pkg/subject"
+)
+
+type vaultV2Fixture struct {
+ Version int `json:"v"`
+ Incarnation string `json:"incarnation"`
+ AttachmentID string `json:"attachmentId"`
+ Revision int64 `json:"revision"`
+ State credentialvault.FileState `json:"state"`
+ StateLineage string `json:"stateLineage"`
+ StateRevision uint64 `json:"stateRevision"`
+ InitializationID string `json:"initializationId,omitempty"`
+ Vault json.RawMessage `json:"vault"`
+}
+
+func encodeVaultV2Fixture(t *testing.T, state credentialvault.FileState, revision int64, stateRevision uint64, initID string, body credentialvault.VaultFileBody) []byte {
+ t.Helper()
+ rawBody, err := json.Marshal(body)
+ require.NoError(t, err)
+ raw, err := json.Marshal(vaultV2Fixture{
+ Version: credentialvault.VaultFileVersion2, Incarnation: testFenceR, AttachmentID: testFenceA,
+ Revision: revision, State: state, StateLineage: "lineage-test", StateRevision: stateRevision,
+ InitializationID: initID, Vault: rawBody,
+ })
+ require.NoError(t, err)
+ return append(raw, '\n')
+}
+
+func emptyVaultFileBody() credentialvault.VaultFileBody {
+ return credentialvault.VaultFileBody{Credentials: []credentialvault.Credential{}, Bindings: []credentialvault.Binding{}}
+}
+
+func seedVaultV2Fixture(h *vaultPersistHarness, uid string, raw []byte) *fakeVaultFile {
+ f := h.fileFor(uid)
+ f.data = append([]byte(nil), raw...)
+ f.exists = true
+ return f
+}
+
+func TestVaultV2ReloadServesActiveButRejectsRelayWrites(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ subj := subject.FromSandboxUID(vaultTestUID)
+ h.srv.mu.Lock()
+ meta := h.srv.vaults[subj].fileMeta
+ h.srv.mu.Unlock()
+ assert.Equal(t, credentialvault.VaultFileVersion2, meta.version)
+ assert.Equal(t, int64(7), meta.revision)
+ assert.Equal(t, credentialvault.FileStateActive, meta.state)
+ assert.Equal(t, "lineage-test", meta.lineage)
+ assert.Equal(t, uint64(12), meta.stateRevision)
+
+ get := doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ require.Equal(t, http.StatusOK, get.Code)
+ assert.Contains(t, get.Body.String(), `"revision":7`)
+ assert.Contains(t, get.Body.String(), "sekret")
+
+ for _, tc := range []struct{ method, body string }{
+ {http.MethodPost, vaultCredential()}, {http.MethodPut, vaultPut("7")}, {http.MethodDelete, ""},
+ } {
+ rec := doVault(t, h.srv, tc.method, vaultTestUID, tc.body, "")
+ assert.Equal(t, http.StatusConflict, rec.Code, tc.method)
+ assert.Equal(t, raw, f.data, "v2 file bytes must not be rewritten")
+ assert.Zero(t, f.saveCalls, "v2 relay writes are rejected before persistence")
+ }
+ assert.Equal(t, int64(7), mustRevision(t, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")), "live last-good remains installed")
+}
+
+func TestVaultV2DeletedReloadIsKnown404ButCannotBeRecreatedYet(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateDeleted, 0, 13, "", emptyVaultFileBody())
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+
+ assert.Equal(t, http.StatusNotFound, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+ rec := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ assert.Equal(t, http.StatusConflict, rec.Code, "a known v2 tombstone is not an uninitialized v1 file")
+ assert.Equal(t, raw, f.data)
+ assert.Zero(t, f.saveCalls)
+ assert.Equal(t, http.StatusNotFound, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+}
+
+func TestVaultV2WrongFenceIsPreservedAndUnavailable(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ raw = []byte(strings.Replace(string(raw), testFenceR, "runtime-foreign", 1))
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "").Code)
+ assert.Equal(t, raw, f.data, "a file from an unverified fence is not purged or rewritten")
+ assert.True(t, f.exists)
+ assert.Zero(t, f.saveCalls)
+}
+
+func TestVaultV2RemoveAndRebindAreRejectedBeforeEnforcement(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ subj := h.readySubject(t, vaultTestUID, vaultTestIP)
+ h.nft.mu.Lock()
+ removedBefore := len(h.nft.removed)
+ h.nft.mu.Unlock()
+
+ remove := doAction(t, h.srv, removeBody(t, vaultTestUID, testFenceR, testFenceA))
+ assert.Equal(t, http.StatusConflict, remove.Code)
+ assert.Equal(t, raw, f.data)
+ _, registered := h.reg.Fence(subj)
+ assert.True(t, registered, "v2 removal is rejected before unregister")
+
+ rebind := doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, "runtime-2", "attachment-2", 2, vaultAllowPolicy()))
+ assert.Equal(t, http.StatusConflict, rebind.Code)
+ assert.Equal(t, raw, f.data, "v2 rebind is rejected before purge")
+ fence, ok := h.reg.Fence(subj)
+ require.True(t, ok)
+ assert.Equal(t, testFenceR, fence.RuntimeInstanceID)
+ assert.Equal(t, testFenceA, fence.AttachmentID)
+ h.nft.mu.Lock()
+ assert.Len(t, h.nft.removed, removedBefore, "rejected lifecycle transitions do not unload enforcement")
+ h.nft.mu.Unlock()
+}
+
+func TestVaultV2UnregisteredRemovePreservesPersistedState(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateDeleted, 0, 13, "", emptyVaultFileBody())
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+
+ rec := doAction(t, h.srv, removeBody(t, vaultTestUID, testFenceR, testFenceA))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ assert.True(t, f.exists)
+ assert.Equal(t, raw, f.data)
+ assert.Zero(t, f.deleteCalls, "unregistered cleanup must check disk before purging")
+}
+
+func TestVaultV2StaleIPTakeoverIsRejectedBeforeEviction(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ victim := h.readySubject(t, vaultTestUID, vaultTestIP)
+ h.nft.mu.Lock()
+ removedBefore := len(h.nft.removed)
+ h.nft.mu.Unlock()
+
+ rec := doAction(t, h.srv, bindBody(t, "successor", vaultTestIP, "runtime-2", "attachment-2", 1, vaultAllowPolicy()))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ assert.Equal(t, raw, f.data, "stale-IP takeover must not purge the victim's v2 state")
+ _, victimRegistered := h.reg.Fence(victim)
+ assert.True(t, victimRegistered)
+ _, successorRegistered := h.reg.Fence(subject.FromSandboxUID("successor"))
+ assert.False(t, successorRegistered)
+ h.nft.mu.Lock()
+ assert.Len(t, h.nft.removed, removedBefore, "stale-IP takeover must be rejected before enforcement unload")
+ h.nft.mu.Unlock()
+}
+
+func TestVaultV2EmptyAndUnknownStateDoNotBecomeAbsent(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ raw []byte
+ }{
+ {name: "explicit empty without mode protocol", raw: encodeVaultV2Fixture(t, credentialvault.FileStateEmpty, 0, 1, "init-1", emptyVaultFileBody())},
+ {name: "unknown future schema", raw: []byte(`{"v":9,"incarnation":"rt","attachmentId":"att","revision":0,"vault":{}}` + "\n")},
+ {name: "truncated v2 envelope", raw: []byte(`{"v":2,"incarnation":"rt"`)},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ f := seedVaultV2Fixture(h, vaultTestUID, tc.raw)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ if tc.name == "explicit empty without mode protocol" {
+ subj := subject.FromSandboxUID(vaultTestUID)
+ h.srv.mu.Lock()
+ meta := h.srv.vaults[subj].fileMeta
+ h.srv.mu.Unlock()
+ assert.Equal(t, credentialvault.FileStateEmpty, meta.state)
+ assert.Equal(t, "lineage-test", meta.lineage)
+ assert.Equal(t, uint64(1), meta.stateRevision)
+ assert.Equal(t, "init-1", meta.initializationID)
+ }
+
+ get := doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ assert.Equal(t, http.StatusServiceUnavailable, get.Code, "unverifiable state must not look like an ordinary 404")
+ post := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ assert.Equal(t, http.StatusServiceUnavailable, post.Code)
+ assert.Equal(t, tc.raw, f.data)
+ assert.True(t, f.exists, "unknown/explicit bytes must be preserved")
+ assert.Zero(t, f.saveCalls)
+ })
+ }
+}
+
+func TestVaultV2ExportAndImportFailBeforeSideEffects(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ active := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ f := seedVaultV2Fixture(h, snapshotTestUID, active)
+ h.readySubject(t, snapshotTestUID, snapshotTestIP)
+
+ legacyBundle := filepath.Join(t.TempDir(), "bundle", "v1.json")
+ h.seedBundle(t, legacyBundle)
+ before := append([]byte(nil), f.data...)
+ importRec := doAction(t, h.srv, snapshotBody(t, snapshotTestUID, testFenceR, testFenceA, "VAULT_IMPORT", legacyBundle))
+ assert.Equal(t, http.StatusConflict, importRec.Code, "v1 bundle must not restamp over a v2 file")
+ assert.Equal(t, before, f.data)
+ assert.Zero(t, f.saveCalls)
+ assert.Equal(t, int64(7), mustRevision(t, doVault(t, h.srv, http.MethodGet, snapshotTestUID, "", "")))
+
+ exportPath := filepath.Join(t.TempDir(), "bundle", "v2.json")
+ exportRec := doAction(t, h.srv, snapshotBody(t, snapshotTestUID, testFenceR, testFenceA, "VAULT_EXPORT", exportPath))
+ assert.Equal(t, http.StatusConflict, exportRec.Code, "v2 cannot be exported when the receiving side cannot restore its lineage")
+ assert.False(t, h.fakeForPath(exportPath).exists, "v2 export fails before writing a bundle")
+ assert.False(t, h.srv.vaultSealedLocked(subject.FromSandboxUID(snapshotTestUID)), "v2 export fails before sealing the subject")
+ assert.Equal(t, before, f.data)
+}
+
+func TestVaultV2BundleImportIsRejectedBeforeRestamp(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ path := filepath.Join(t.TempDir(), "bundle", "v2.json")
+ require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o700))
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 4, 8, "", bundleVaultBody(t))
+ require.NoError(t, os.WriteFile(path, raw, 0o600))
+
+ rec := doAction(t, h.srv, snapshotBody(t, "fresh-destination", snapshotResumeR, snapshotResumeA, "VAULT_IMPORT", path))
+ assert.Equal(t, http.StatusConflict, rec.Code)
+ f := h.fileFor("fresh-destination")
+ assert.False(t, f.exists, "unsupported v2 import must not create a destination file")
+ assert.Zero(t, f.saveCalls)
+}
+
+func TestLegacyV1BundleReplayRemainsV1(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ path := filepath.Join(t.TempDir(), "bundle", snapshotTestUID+".json")
+ h.seedBundle(t, path)
+ transfer := snapshotBody(t, snapshotTestUID, snapshotResumeR, snapshotResumeA, "VAULT_IMPORT", path)
+
+ first := doAction(t, h.srv, transfer)
+ require.Equal(t, http.StatusOK, first.Code)
+ f := h.fileFor(snapshotTestUID)
+ require.True(t, f.exists)
+ vf, _, err := credentialvault.DecodeVaultFile(f.data)
+ require.NoError(t, err)
+ require.Equal(t, credentialvault.VaultFileVersion, vf.Version)
+ firstBytes := append([]byte(nil), f.data...)
+
+ second := doAction(t, h.srv, transfer)
+ assert.Equal(t, http.StatusOK, second.Code)
+ assert.Equal(t, firstBytes, f.data, "retrying a v1 transfer does not silently upgrade or restamp it differently")
+ assert.Equal(t, 2, f.saveCalls)
+}
+
+func TestLegacyV1ImportStillRepairsCorruptLocalFile(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ bundlePath := filepath.Join(t.TempDir(), "bundle", snapshotTestUID+".json")
+ h.seedBundle(t, bundlePath)
+ f := h.fileFor(snapshotTestUID)
+ f.data = []byte("{corrupt legacy v1 file")
+ f.exists = true
+
+ rec := doAction(t, h.srv, snapshotBody(t, snapshotTestUID, snapshotResumeR, snapshotResumeA, "VAULT_IMPORT", bundlePath))
+ require.Equal(t, http.StatusOK, rec.Code)
+ assert.Equal(t, 1, f.saveCalls, "the existing v1 import recovery path remains available")
+ vf, _, err := credentialvault.DecodeVaultFile(f.data)
+ require.NoError(t, err)
+ assert.Equal(t, credentialvault.VaultFileVersion, vf.Version)
+}
+
+func TestVaultV2DecoderRetainsOrderingMetadata(t *testing.T) {
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateDeleted, 0, 13, "", emptyVaultFileBody())
+ vf, body, err := credentialvault.DecodeVaultFile(raw)
+ require.NoError(t, err)
+ assert.Equal(t, credentialvault.VaultFileVersion2, vf.Version)
+ assert.Equal(t, credentialvault.FileStateDeleted, vf.State)
+ assert.Equal(t, "lineage-test", vf.StateLineage)
+ assert.Equal(t, uint64(13), vf.StateRevision)
+ assert.Empty(t, body.Credentials)
+ assert.Empty(t, body.Bindings)
+ emptyRaw := encodeVaultV2Fixture(t, credentialvault.FileStateEmpty, 0, 14, "init-authority-1", emptyVaultFileBody())
+ emptyFile, _, err := credentialvault.DecodeVaultFile(emptyRaw)
+ require.NoError(t, err)
+ assert.Equal(t, "init-authority-1", emptyFile.InitializationID, "read-only decoding retains the initialization identity")
+}
+
+func TestVaultV2MalformedEnvelopeIsPreservedAsUnsupported(t *testing.T) {
+ for _, raw := range [][]byte{
+ []byte(`{"v":2,"incarnation":"rt"`),
+ []byte(`{"v":2,"v":1,"incarnation":"rt","attachmentId":"att","revision":1,"vault":{"credentials":[],"bindings":[]}}`),
+ } {
+ _, _, err := credentialvault.DecodeVaultFile(raw)
+ require.Error(t, err)
+ assert.ErrorIs(t, err, credentialvault.ErrUnsupportedFileVersion)
+ }
+}
+
+func TestVaultV2SnapshotFailureBlocksWriteUntilSameFenceRetry(t *testing.T) {
+ for _, failure := range []string{"storeFor", "snapshot"} {
+ t.Run(failure, func(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ raw := encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))
+ f := seedVaultV2Fixture(h, vaultTestUID, raw)
+ if failure == "storeFor" {
+ h.newFileErr = errors.New("temporary store error")
+ } else {
+ f.snapErr = errors.New("temporary snapshot error")
+ }
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ f.snapErr = nil
+
+ get := doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ assert.Equal(t, http.StatusServiceUnavailable, get.Code, "unreadable persisted state must not look absent")
+ post := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ assert.Equal(t, http.StatusServiceUnavailable, post.Code)
+ assert.Equal(t, raw, f.data, "a transient reload error must not let POST downgrade v2 to v1")
+ assert.Zero(t, f.saveCalls)
+
+ // A same-fence SET_BINDING replay retries the read. Once storage
+ // recovers, v2 active reloads and stays protected by the read-only guard.
+ retry := doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, testFenceR, testFenceA, 2, vaultAllowPolicy()))
+ require.Equal(t, http.StatusOK, retry.Code)
+ get = doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ require.Equal(t, http.StatusOK, get.Code)
+ assert.Contains(t, get.Body.String(), `"revision":7`)
+ post = doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ assert.Equal(t, http.StatusConflict, post.Code)
+ assert.Equal(t, raw, f.data)
+ assert.Zero(t, f.saveCalls)
+ })
+ }
+}
+
+func TestVaultKnownProtectedStateMissingRemainsUnknownOnSameFenceReload(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ raw []byte
+ }{
+ {name: "explicit empty v2", raw: encodeVaultV2Fixture(t, credentialvault.FileStateEmpty, 0, 14, "init-1", emptyVaultFileBody())},
+ {name: "foreign fence v2", raw: []byte(strings.Replace(string(encodeVaultV2Fixture(t, credentialvault.FileStateActive, 7, 12, "", bundleVaultBody(t))), testFenceR, "runtime-foreign", 1))},
+ {name: "unknown schema", raw: []byte(`{"v":9,"incarnation":"runtime-1","attachmentId":"attachment-1","revision":7,"vault":{}}` + "\n")},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ f := seedVaultV2Fixture(h, vaultTestUID, tc.raw)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+
+ // Simulate the protected file disappearing after it was observed.
+ // A same-fence SET replay must not turn that history into v1 absence.
+ f.data, f.exists = nil, false
+ retry := doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, testFenceR, testFenceA, 2, vaultAllowPolicy()))
+ require.Equal(t, http.StatusOK, retry.Code)
+ get := doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ post := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ assert.Equal(t, http.StatusServiceUnavailable, get.Code, "known protected history must remain unavailable after the file disappears")
+ assert.Equal(t, http.StatusServiceUnavailable, post.Code, "missing protected state must not be treated as a fresh v1 Vault")
+ assert.False(t, f.exists)
+ assert.Zero(t, f.saveCalls)
+ })
+ }
+}
+
+func TestVaultTransientFirstReadFailureCanRecoverToV1(t *testing.T) {
+ for _, failure := range []string{"storeFor", "snapshot"} {
+ t.Run(failure, func(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ h.seedVaultFile(vaultTestUID, testFenceR, testFenceA, 7, `{"credentials":[],"bindings":[]}`)
+ f := h.fileFor(vaultTestUID)
+ if failure == "storeFor" {
+ h.newFileErr = errors.New("temporary store error")
+ } else {
+ f.snapErr = errors.New("temporary snapshot error")
+ }
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ f.snapErr = nil
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+
+ retry := doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, testFenceR, testFenceA, 2, vaultAllowPolicy()))
+ require.Equal(t, http.StatusOK, retry.Code)
+ get := doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "")
+ require.Equal(t, http.StatusOK, get.Code, "a transient read failure must clear when the same fence reads a v1 file")
+ assert.Contains(t, get.Body.String(), `"revision":7`)
+ put := doVault(t, h.srv, http.MethodPut, vaultTestUID, vaultPut("7"), "")
+ require.Equal(t, http.StatusOK, put.Code, "recovered v1 state accepts its normal conditional update")
+ assert.Contains(t, put.Body.String(), `"revision":8`)
+ assert.True(t, f.exists)
+ assert.Equal(t, 1, f.saveCalls)
+ })
+ }
+}
+
+func TestVaultKnownProtectedStateCannotReloadLegacyOnSameFence(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ seedVaultV2Fixture(h, vaultTestUID, encodeVaultV2Fixture(t, credentialvault.FileStateEmpty, 0, 14, "init-1", emptyVaultFileBody()))
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+
+ // A successful v1 read after a known explicit state would imply an
+ // out-of-band downgrade. It must not erase the already observed provenance.
+ h.seedVaultFile(vaultTestUID, testFenceR, testFenceA, 7, `{"credentials":[],"bindings":[]}`)
+ f := h.fileFor(vaultTestUID)
+ v1 := append([]byte(nil), f.data...)
+ retry := doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, testFenceR, testFenceA, 2, vaultAllowPolicy()))
+ require.Equal(t, http.StatusOK, retry.Code)
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodGet, vaultTestUID, "", "").Code)
+ assert.Equal(t, http.StatusServiceUnavailable, doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "").Code)
+ assert.Equal(t, v1, f.data, "the legacy file is left untouched for diagnosis/recovery")
+ assert.Zero(t, f.saveCalls)
+}
+
+func TestRemoveBindingV1PurgeFailureKeepsBestEffortAck(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ post := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ require.Equal(t, http.StatusCreated, post.Code)
+ f := h.fileFor(vaultTestUID)
+ f.deleteErr = errors.New("simulated v1 unlink failure")
+
+ var rec *httptest.ResponseRecorder
+ panicked := false
+ func() {
+ defer func() { panicked = recover() != nil }()
+ rec = doAction(t, h.srv, removeBody(t, vaultTestUID, testFenceR, testFenceA))
+ }()
+ assert.False(t, panicked, "an I/O failure must not turn status 0 into an invalid WriteHeader")
+ if panicked {
+ return
+ }
+ require.NotNil(t, rec)
+ assert.Equal(t, http.StatusOK, rec.Code, "legacy v1 cleanup retains its best-effort acknowledgement")
+ assert.True(t, f.exists, "the failed v1 purge leaves the file for retry/recovery")
+ assert.Equal(t, 1, f.deleteCalls)
+}
+
+func TestRebindV1PurgeFailureKeepsBestEffortAck(t *testing.T) {
+ h := newVaultPersistHarness(t)
+ h.readySubject(t, vaultTestUID, vaultTestIP)
+ post := doVault(t, h.srv, http.MethodPost, vaultTestUID, vaultCredential(), "")
+ require.Equal(t, http.StatusCreated, post.Code)
+ f := h.fileFor(vaultTestUID)
+ f.deleteErr = errors.New("simulated v1 unlink failure")
+
+ var rec *httptest.ResponseRecorder
+ panicked := false
+ func() {
+ defer func() { panicked = recover() != nil }()
+ rec = doAction(t, h.srv, bindBody(t, vaultTestUID, vaultTestIP, "runtime-2", "attachment-2", 2, vaultAllowPolicy()))
+ }()
+ assert.False(t, panicked, "an I/O failure must not turn status 0 into an invalid WriteHeader")
+ if panicked {
+ return
+ }
+ require.NotNil(t, rec)
+ assert.Equal(t, http.StatusOK, rec.Code, "legacy v1 rebind cleanup retains its best-effort acknowledgement")
+ assert.True(t, f.exists, "the failed v1 purge leaves the file for retry/recovery")
+ assert.GreaterOrEqual(t, f.deleteCalls, 1)
+ newFence, ok := h.reg.Fence(subject.FromSandboxUID(vaultTestUID))
+ require.True(t, ok)
+ assert.Equal(t, "runtime-2", newFence.RuntimeInstanceID)
+ assert.Equal(t, "attachment-2", newFence.AttachmentID)
+}
diff --git a/components/egress/pkg/credentialvault/vaultfile.go b/components/egress/pkg/credentialvault/vaultfile.go
index 465e7c622..d1a9b5888 100644
--- a/components/egress/pkg/credentialvault/vaultfile.go
+++ b/components/egress/pkg/credentialvault/vaultfile.go
@@ -23,15 +23,24 @@ import (
"encoding/json"
"errors"
"fmt"
+ "io"
"strings"
)
-// VaultFileVersion is the only supported on-disk schema version. Anything
-// else — including a missing one — is rejected rather than misinterpreted;
-// the rejection is identifiable via ErrUnsupportedFileVersion so callers can
-// preserve files written by a newer consumer.
+// VaultFileVersion is the original write schema. This compatibility stage
+// keeps writing v1 while safely reading v2 as read-only state.
const VaultFileVersion = 1
+const VaultFileVersion2 = 2
+
+type FileState string
+
+const (
+ FileStateActive FileState = "active"
+ FileStateDeleted FileState = "deleted"
+ FileStateEmpty FileState = "empty"
+)
+
// MaxEncodedVaultFileBytes bounds one encoded vault file: a relay body up to
// maxCredentialVaultBodyBytes plus the envelope (version, fence, revision,
// JSON framing). Consumers sizing storage or transfers for vault files use
@@ -48,11 +57,27 @@ var ErrUnsupportedFileVersion = errors.New("unsupported vault file version")
// the SET_BINDING envelope; a registration under a different fence — a reset,
// or a rebind that changed only the attachment — finds the file stale.
type VaultFile struct {
- Version int `json:"v"`
- Incarnation string `json:"incarnation"`
- AttachmentID string `json:"attachmentId"`
- Revision int64 `json:"revision"`
- Vault json.RawMessage `json:"vault"`
+ Version int `json:"v"`
+ Incarnation string `json:"incarnation"`
+ AttachmentID string `json:"attachmentId"`
+ Revision int64 `json:"revision"`
+ Vault json.RawMessage `json:"vault"`
+ State FileState `json:"-"`
+ StateLineage string `json:"-"`
+ StateRevision uint64 `json:"-"`
+ InitializationID string `json:"-"`
+}
+
+type vaultFileV2 struct {
+ Version int `json:"v"`
+ Incarnation string `json:"incarnation"`
+ AttachmentID string `json:"attachmentId"`
+ Revision int64 `json:"revision"`
+ State FileState `json:"state"`
+ StateLineage string `json:"stateLineage"`
+ StateRevision uint64 `json:"stateRevision"`
+ InitializationID string `json:"initializationId,omitempty"`
+ Vault json.RawMessage `json:"vault"`
}
// VaultFileBody is the OSEP-0012 vault JSON carried in VaultFile.Vault —
@@ -95,29 +120,37 @@ func EncodeVaultFile(incarnation, attachmentID string, revision int64, body Vaul
return append(out, '\n'), nil
}
-// DecodeVaultFile parses and validates file bytes. The version discriminator
-// is read FIRST with a tolerant view: a newer envelope carries unknown
-// fields, so the strict v1 schema must not reject (and the caller quarantine)
-// a file this reader should merely preserve. Only strictly newer versions
-// surface ErrUnsupportedFileVersion; a missing or invalid version is plain
-// corruption. The v1 schema then enforces exactly the known fields, non-blank
-// fence fields, a positive revision, and a decodable create-shaped body;
-// semantic validation (credential references, policy coverage, ambiguity) is
-// the store's job at load time.
+// DecodeVaultFile parses v1 and the read-only v2 envelope. Unknown versions
+// and v2 shapes this build cannot interpret are reported as unsupported so
+// callers preserve the original bytes rather than quarantine or rewrite them.
func DecodeVaultFile(data []byte) (VaultFile, VaultFileBody, error) {
var body VaultFileBody
trimmed := bytes.TrimSpace(data)
if len(trimmed) == 0 {
return VaultFile{}, body, fmt.Errorf("vault file is empty")
}
+ hintedVersion, hasHintedVersion, duplicateVersion := vaultFileVersionHint(trimmed)
var disc struct {
Version *int `json:"v"`
}
if err := json.Unmarshal(trimmed, &disc); err != nil {
+ if hasHintedVersion && hintedVersion >= VaultFileVersion2 {
+ return VaultFile{}, body, fmt.Errorf("%w %d (malformed v2+ envelope): %v", ErrUnsupportedFileVersion, hintedVersion, err)
+ }
return VaultFile{}, body, fmt.Errorf("decode vault file envelope: %w", err)
}
- if disc.Version != nil && *disc.Version > VaultFileVersion {
- return VaultFile{}, body, fmt.Errorf("%w %d (newer than supported %d)", ErrUnsupportedFileVersion, *disc.Version, VaultFileVersion)
+ if duplicateVersion && hasHintedVersion && hintedVersion >= VaultFileVersion2 {
+ return VaultFile{}, body, fmt.Errorf("%w %d (duplicate version fields are ambiguous)", ErrUnsupportedFileVersion, hintedVersion)
+ }
+ if disc.Version != nil && *disc.Version > VaultFileVersion2 {
+ return VaultFile{}, body, fmt.Errorf("%w %d (newer than supported %d)", ErrUnsupportedFileVersion, *disc.Version, VaultFileVersion2)
+ }
+ if disc.Version != nil && *disc.Version == VaultFileVersion2 {
+ vf, body, err := decodeVaultFileV2(trimmed)
+ if err != nil {
+ return VaultFile{}, VaultFileBody{}, fmt.Errorf("%w: v2 vault file cannot be interpreted safely: %v", ErrUnsupportedFileVersion, err)
+ }
+ return vf, body, nil
}
var vf VaultFile
dec := json.NewDecoder(bytes.NewReader(trimmed))
@@ -147,3 +180,107 @@ func DecodeVaultFile(data []byte) (VaultFile, VaultFileBody, error) {
}
return vf, body, nil
}
+
+// vaultFileVersionHint scans top-level version fields even when a later field
+// is truncated. It records the highest numeric version and whether the field
+// was repeated, so an ambiguous envelope containing v2 cannot be decoded as
+// v1 just because the last duplicate happens to say v1.
+func vaultFileVersionHint(data []byte) (int, bool, bool) {
+ dec := json.NewDecoder(bytes.NewReader(data))
+ tok, err := dec.Token()
+ if err != nil || tok != json.Delim('{') {
+ return 0, false, false
+ }
+ version, found, duplicate := 0, false, false
+ for dec.More() {
+ keyToken, err := dec.Token()
+ if err != nil {
+ return version, found, duplicate
+ }
+ key, ok := keyToken.(string)
+ if !ok {
+ return version, found, duplicate
+ }
+ if key == "v" {
+ var raw json.RawMessage
+ if err := dec.Decode(&raw); err != nil {
+ return version, found, duplicate
+ }
+ var parsed *int
+ if err := json.Unmarshal(raw, &parsed); err != nil || parsed == nil {
+ continue
+ }
+ if found {
+ duplicate = true
+ }
+ if *parsed > version {
+ version = *parsed
+ }
+ found = true
+ continue
+ }
+ var ignored json.RawMessage
+ if err := dec.Decode(&ignored); err != nil {
+ return version, found, duplicate
+ }
+ }
+ return version, found, duplicate
+}
+
+func decodeVaultFileV2(data []byte) (VaultFile, VaultFileBody, error) {
+ var wire vaultFileV2
+ if err := decodeSingleJSON(data, &wire); err != nil {
+ return VaultFile{}, VaultFileBody{}, err
+ }
+ if wire.Version != VaultFileVersion2 {
+ return VaultFile{}, VaultFileBody{}, fmt.Errorf("invalid vault file version %d", wire.Version)
+ }
+ if strings.TrimSpace(wire.Incarnation) == "" || strings.TrimSpace(wire.AttachmentID) == "" {
+ return VaultFile{}, VaultFileBody{}, errors.New("v2 vault file fence cannot be blank")
+ }
+ if strings.TrimSpace(wire.StateLineage) == "" || wire.StateRevision == 0 {
+ return VaultFile{}, VaultFileBody{}, errors.New("v2 vault file order token is incomplete")
+ }
+ var body VaultFileBody
+ if len(wire.Vault) == 0 || !json.Valid(wire.Vault) {
+ return VaultFile{}, VaultFileBody{}, errors.New("v2 vault file body is missing or invalid")
+ }
+ if err := decodeSingleJSON(wire.Vault, &body); err != nil {
+ return VaultFile{}, VaultFileBody{}, fmt.Errorf("decode v2 vault body: %w", err)
+ }
+ switch wire.State {
+ case FileStateActive:
+ if wire.Revision < 1 {
+ return VaultFile{}, VaultFileBody{}, errors.New("active v2 vault revision must be positive")
+ }
+ case FileStateDeleted, FileStateEmpty:
+ if wire.Revision != 0 || len(body.Credentials) != 0 || len(body.Bindings) != 0 {
+ return VaultFile{}, VaultFileBody{}, fmt.Errorf("%s v2 vault must have revision 0 and an empty body", wire.State)
+ }
+ if wire.State == FileStateEmpty && strings.TrimSpace(wire.InitializationID) == "" {
+ return VaultFile{}, VaultFileBody{}, errors.New("empty v2 vault requires an initialization ID")
+ }
+ default:
+ return VaultFile{}, VaultFileBody{}, fmt.Errorf("unsupported v2 vault state %q", wire.State)
+ }
+ return VaultFile{
+ Version: VaultFileVersion2, Incarnation: wire.Incarnation, AttachmentID: wire.AttachmentID,
+ Revision: wire.Revision, Vault: append(json.RawMessage(nil), wire.Vault...), State: wire.State,
+ StateLineage: wire.StateLineage, StateRevision: wire.StateRevision, InitializationID: wire.InitializationID,
+ }, body, nil
+}
+
+func decodeSingleJSON(data []byte, out any) error {
+ dec := json.NewDecoder(bytes.NewReader(data))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(out); err != nil {
+ return err
+ }
+ var extra any
+ if err := dec.Decode(&extra); err == nil {
+ return errors.New("multiple JSON values")
+ } else if !errors.Is(err, io.EOF) {
+ return err
+ }
+ return nil
+}