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.goindex 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 *actidefer 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 *actireturn 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 = falsetoken.oldRemoved = truetoken.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.Envelopelog.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] == tokenif 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.goindex 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] != nildelete(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.goindex 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, rif 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 := effectivevar (@@ -292,6 +302,9 @@ func (s *fastSandboxPolicyServer) readRelayVault(r *http.Request, subj subject.Sif 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", nildiff --git a/components/egress/fastsandbox_vault_persist.go b/components/egress/fastsandbox_vault_persist.goindex 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 = trues.vaults[subj] = entrylog.Warnf("subject %s: %s", subj, entry.degraded)return@@ -500,15 +560,41 @@ func (s *fastSandboxPolicyServer) rehydrateVaultReload(subj subject.Subject, fenswitch {case err != nil:entry.degraded = fmt.Sprintf("vault file unreadable: %v", err)+ entry.vaultStateUnknown = truelog.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 = truelog.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 = truelog.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.VaultFileVersion2log.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.goindex 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.goindex 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 stringfiles map[string]*fakeVaultFilemapMu sync.Mutex+ newFileErr error}func newVaultPersistHarness(t *testing.T) *vaultPersistHarness {@@ -169,6 +170,11 @@ func newTestVaultPersistence(t *testing.T, h *vaultPersistHarness) *vaultPersistvp, 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.goindex 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.gonew file mode 100644index 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.goindex 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 Vaulreturn 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 VaultFileBodytrimmed := 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 VaultFiledec := 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+}