Merge branch 'fix/crypto-vault-disk-persistence' into develop

Fix on-disk crypto vault: ZipFileSystem.ListAsync no longer crashes on
ZipArchiveEntry.Length in update mode, and CryptoFileSystem.Dispose flushes
its inner filesystem so RegisterCryptoVault persists to disk.

Author: tgiachi

docs/tutorials/vfs.md

@@ -31,14 +31,14 @@ The same `IVirtualFileSystem` API works regardless of the backend. `ReadAllBytes
 ### 3. Encrypted vault round-trip
 
 `CryptoFileSystem` encrypts every entry over a backend filesystem. The lifecycle is
-unlock → write → lock; locking zeroes the key and flushes the encrypted index into the backend,
-so re-opening the same backend with the passphrase decrypts the data at rest.
-
-This sample drives `CryptoFileSystem` over an **in-memory** backend to demonstrate the full
-lifecycle. The DI helper `RegisterCryptoVault` wires a vault over a single on-disk zip file, but
-that `ZipFileSystem` backend currently cannot be locked/persisted (a known limitation — its
-`List` reads `ZipArchiveEntry.Length`, which .NET marks unavailable in `ZipArchiveMode.Update`).
-On-disk vault persistence is therefore not yet supported.
+unlock → write → dispose; disposing locks the vault (zeroing the key and flushing the encrypted
+index) and disposes the backend, so a `ZipFileSystem` backend flushes its archive to disk.
+Re-opening a fresh instance over the same file with the passphrase decrypts the data at rest.
+
+This sample backs the vault with a single on-disk zip file via `ZipFileSystem`, writes a secret,
+disposes the vault, then re-opens a brand-new instance over the same file to prove on-disk
+persistence. The DI helper `RegisterCryptoVault` wires exactly this — a vault over a single-file
+zip — as a lockable singleton.
 
 [!code-csharp[](../../samples/SquidStd.Samples.Vfs/Program.cs#step-3)]
 

samples/SquidStd.Samples.Vfs/Program.cs

@@ -38,30 +38,27 @@
 
 #region step-3
 
-// Encrypted vault lifecycle: unlock -> write -> lock, then re-open and read.
-// RegisterCryptoVault wires a DI vault over a single on-disk zip file, but that ZipFileSystem
-// backend currently cannot be locked/persisted (its List reads ZipArchiveEntry.Length, which
-// .NET marks unavailable in ZipArchiveMode.Update), so this sample drives CryptoFileSystem over
-// an in-memory backend to demonstrate the full lifecycle without that limitation.
-var backend = new InMemoryFileSystem();
-
-using (var vault = new CryptoFileSystem(backend))
+// Encrypted vault on a single on-disk zip file: unlock -> write -> dispose (flushes to disk),
+// then re-open a brand-new instance over the same file to prove the data round-trips at rest.
+var vaultPath = Path.Combine(Path.GetTempPath(), "squidstd-sample.vault");
+
+using (var vault = new CryptoFileSystem(new ZipFileSystem(vaultPath)))
 {
     vault.Unlock("vault passphrase");
     await vault.WriteAllBytesAsync("secret.txt", Encoding.UTF8.GetBytes("top secret"));
-    vault.Lock(); // zeroes the key and flushes the encrypted index into the backend
-}
+} // Dispose -> Lock (zeroes the key, flushes the encrypted index) -> flushes the zip to disk
 
-// Re-open the same encrypted backend with the passphrase to prove the data round-trips at rest.
-using (var reopened = new CryptoFileSystem(backend))
+// Re-open the same encrypted file with the passphrase; only the right passphrase decrypts it.
+using (var reopened = new CryptoFileSystem(new ZipFileSystem(vaultPath)))
 {
     reopened.Unlock("vault passphrase");
 
-    // The secret was written above, so it is present.
     var secret = await reopened.ReadAllBytesAsync("secret.txt");
     Console.WriteLine($"Vault read after reopen: {Encoding.UTF8.GetString(secret!)}");
 }
 
+File.Delete(vaultPath);
+
 #endregion
 
 await bootstrap.StopAsync();

src/SquidStd.Crypto/Vfs/Services/CryptoFileSystem.cs

@@ -232,6 +232,18 @@ private void EnsureUnlocked()
     public void Dispose()
     {
         Lock();
+
+        // The vault owns its inner filesystem; disposing it flushes backends such as ZipFileSystem
+        // (which only writes its archive to disk on dispose) so the vault persists.
+        switch (_inner)
+        {
+            case IDisposable disposable:
+                disposable.Dispose();
+                break;
+            case IAsyncDisposable asyncDisposable:
+                asyncDisposable.DisposeAsync().AsTask().GetAwaiter().GetResult();
+                break;
+        }
     }
 
     private sealed class VaultWriteStream : MemoryStream

src/SquidStd.Vfs/Services/ZipFileSystem.cs

@@ -11,6 +11,7 @@ public sealed class ZipFileSystem : IVirtualFileSystem, IAsyncDisposable, IDispo
 {
     private readonly ZipArchive _archive;
     private readonly FileStream _file;
+    private readonly Dictionary<string, long> _writtenLengths = new(StringComparer.Ordinal);
 
     public ZipFileSystem(string path)
     {
@@ -50,6 +51,10 @@ public async ValueTask WriteAllBytesAsync(
 
         await using var stream = entry.Open();
         await stream.WriteAsync(data, cancellationToken).ConfigureAwait(false);
+
+        // ZipArchiveEntry.Length is unavailable in update mode once an entry has been opened for
+        // writing, so track the uncompressed size ourselves for ListAsync.
+        _writtenLengths[name] = data.Length;
     }
 
     public async Task<Stream> OpenReadAsync(string path, CancellationToken cancellationToken = default)
@@ -67,14 +72,16 @@ public Task<Stream> OpenWriteAsync(string path, CancellationToken cancellationTo
 
     public ValueTask<bool> DeleteAsync(string path, CancellationToken cancellationToken = default)
     {
-        var entry = _archive.GetEntry(VfsPath.Normalize(path));
+        var name = VfsPath.Normalize(path);
+        var entry = _archive.GetEntry(name);
 
         if (entry is null)
         {
             return ValueTask.FromResult(false);
         }
 
         entry.Delete();
+        _writtenLengths.Remove(name);
 
         return ValueTask.FromResult(true);
     }
@@ -92,12 +99,31 @@ public async IAsyncEnumerable<VfsEntry> ListAsync(
                 continue;
             }
 
-            yield return new VfsEntry(entry.FullName, entry.Length, entry.LastWriteTime);
+            yield return new VfsEntry(entry.FullName, EntrySize(entry), entry.LastWriteTime);
 
             await Task.CompletedTask;
         }
     }
 
+    private long EntrySize(ZipArchiveEntry entry)
+    {
+        if (_writtenLengths.TryGetValue(entry.FullName, out var length))
+        {
+            return length;
+        }
+
+        try
+        {
+            return entry.Length;
+        }
+        catch (InvalidOperationException)
+        {
+            // Unavailable in update mode for an entry opened for writing this session that we did
+            // not track (should not happen, but never let listing throw).
+            return 0;
+        }
+    }
+
     public async ValueTask DisposeAsync()
     {
         _archive.Dispose();

tests/SquidStd.Tests/Crypto/Vfs/CryptoFileSystemDiskTests.cs

@@ -0,0 +1,73 @@
+using System.Text;
+using SquidStd.Crypto.Vfs.Data;
+using SquidStd.Crypto.Vfs.Services;
+using SquidStd.Vfs.Services;
+
+namespace SquidStd.Tests.Crypto.Vfs;
+
+public class CryptoFileSystemDiskTests
+{
+    private static CryptoVaultOptions FastOptions()
+    {
+        return new CryptoVaultOptions { Argon2MemoryKib = 8192, Argon2Iterations = 1 };
+    }
+
+    [Fact]
+    public async Task Lock_AfterWrites_OverZipBackend_DoesNotThrow()
+    {
+        var path = Path.Combine(Path.GetTempPath(), "squidstd-vault-" + Guid.NewGuid().ToString("N") + ".vault");
+
+        try
+        {
+            var vault = new CryptoFileSystem(new ZipFileSystem(path), FastOptions());
+            vault.Unlock("pw");
+            await vault.WriteAllBytesAsync("secret.txt", Encoding.UTF8.GetBytes("top secret"));
+
+            // PruneOrphans() lists the zip backend, which previously threw because ZipArchiveEntry.Length
+            // is unavailable in update mode after a same-session write.
+            vault.Lock();
+
+            Assert.False(vault.IsUnlocked);
+        }
+        finally
+        {
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+    }
+
+    [Fact]
+    public async Task Vault_PersistsToDisk_AcrossInstances()
+    {
+        var path = Path.Combine(Path.GetTempPath(), "squidstd-vault-" + Guid.NewGuid().ToString("N") + ".vault");
+
+        try
+        {
+            using (var vault = new CryptoFileSystem(new ZipFileSystem(path), FastOptions()))
+            {
+                vault.Unlock("correct horse");
+                await vault.WriteAllBytesAsync("notes/plan.txt", Encoding.UTF8.GetBytes("attack at dawn"));
+            } // Dispose -> Lock -> flush the inner zip to disk
+
+            Assert.True(new FileInfo(path).Length > 0, "the vault file must be written to disk");
+
+            using (var reopened = new CryptoFileSystem(new ZipFileSystem(path), FastOptions()))
+            {
+                reopened.Unlock("correct horse");
+                var data = await reopened.ReadAllBytesAsync("notes/plan.txt");
+
+                Assert.NotNull(data);
+                Assert.Equal("attack at dawn", Encoding.UTF8.GetString(data!));
+            }
+        }
+        finally
+        {
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+    }
+}

tests/SquidStd.Tests/Vfs/ZipFileSystemTests.cs

@@ -39,4 +39,39 @@ public async Task Write_Reopen_Read_Delete_RoundTrips()
             }
         }
     }
+
+    [Fact]
+    public async Task ListAsync_AfterWritingInSameSession_DoesNotThrow_AndReportsSizes()
+    {
+        var path = Path.Combine(Path.GetTempPath(), "squidstd-vfs-" + Guid.NewGuid().ToString("N") + ".zip");
+
+        try
+        {
+            await using var fs = new ZipFileSystem(path);
+            await fs.WriteAllBytesAsync("a.txt", Encoding.UTF8.GetBytes("hello"));
+            await fs.WriteAllBytesAsync("b.txt", Encoding.UTF8.GetBytes("hi"));
+
+            var entries = new List<string>();
+            long totalSize = 0;
+
+            // In ZipArchiveMode.Update, ZipArchiveEntry.Length throws for entries written this
+            // session; ListAsync must not surface that.
+            await foreach (var entry in fs.ListAsync())
+            {
+                entries.Add(entry.Path);
+                totalSize += entry.Size;
+            }
+
+            Assert.Contains("a.txt", entries);
+            Assert.Contains("b.txt", entries);
+            Assert.Equal(7, totalSize); // 5 + 2 uncompressed bytes
+        }
+        finally
+        {
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+    }
 }