feat(transport): BundleSerializer ZIP packer/reader

src/ScadaLink.Transport/Serialization/BundleSerializer.cs

@@ -0,0 +1,178 @@
+using System.IO.Compression;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using ScadaLink.Commons.Types.Transport;
+using ScadaLink.Transport.Encryption;
+
+namespace ScadaLink.Transport.Serialization;
+
+/// <summary>
+/// Packs <see cref="BundleContentDto"/> + <see cref="BundleManifest"/> into a
+/// ZIP archive (<c>manifest.json</c> always, plus either <c>content.json</c>
+/// or <c>content.enc</c>) and reverses the operation on read.
+///
+/// When packing with a passphrase, the caller must have already encrypted the
+/// content bytes upstream and built a manifest whose <see cref="EncryptionMetadata"/>
+/// + <c>ContentHash</c> describe those exact bytes. <see cref="Pack"/> uses the
+/// manifest as source of truth: it re-serializes the content (or re-encrypts
+/// with the manifest's salt/iv when needed) so the zip stays internally
+/// consistent. The simpler usage — and the one BundleExporter follows — is to
+/// pre-encrypt, hash, build manifest, then call Pack which trusts the manifest
+/// + re-encrypts to a fresh IV and rebuilds the manifest internally.
+/// </summary>
+public sealed class BundleSerializer
+{
+    private const string ManifestEntryName = "manifest.json";
+    private const string ContentJsonEntryName = "content.json";
+    private const string ContentEncEntryName = "content.enc";
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        WriteIndented = false,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        Converters = { new JsonStringEnumConverter() },
+    };
+
+    /// <summary>
+    /// Serializes the bundle content to its canonical JSON byte form. Exposed
+    /// so callers can compute the content hash (or pre-encrypt) before they
+    /// build the manifest.
+    /// </summary>
+    public byte[] SerializeContentBytes(BundleContentDto content)
+    {
+        ArgumentNullException.ThrowIfNull(content);
+        return JsonSerializer.SerializeToUtf8Bytes(content, JsonOptions);
+    }
+
+    public Stream Pack(
+        BundleContentDto content,
+        BundleManifest manifest,
+        string? passphrase,
+        BundleSecretEncryptor? encryptor)
+    {
+        ArgumentNullException.ThrowIfNull(content);
+        ArgumentNullException.ThrowIfNull(manifest);
+
+        if (passphrase is not null && encryptor is null)
+        {
+            throw new ArgumentException("Encryptor is required when a passphrase is supplied.", nameof(encryptor));
+        }
+        if (passphrase is not null && manifest.Encryption is null)
+        {
+            throw new ArgumentException("Manifest must carry EncryptionMetadata when packing an encrypted bundle.", nameof(manifest));
+        }
+
+        var contentBytes = SerializeContentBytes(content);
+        byte[] payload;
+        string payloadEntryName;
+        BundleManifest finalManifest;
+
+        if (passphrase is not null && encryptor is not null && manifest.Encryption is not null)
+        {
+            // Fresh encryption — re-derives salt/iv. The manifest passed in described
+            // the upstream encrypt; we honour the requested algorithm/kdf/iteration
+            // count but rebuild ContentHash + Encryption fields against the bytes we
+            // actually write. The non-encryption manifest fields (source env, exported
+            // by, summary, contents, version) are preserved verbatim.
+            var (cipher, freshMeta) = encryptor.Encrypt(contentBytes, passphrase, manifest.Encryption.Iterations);
+            payload = cipher;
+            payloadEntryName = ContentEncEntryName;
+            finalManifest = manifest with
+            {
+                Encryption = freshMeta,
+                ContentHash = "sha256:" + Convert.ToHexString(
+                    System.Security.Cryptography.SHA256.HashData(cipher)).ToLowerInvariant(),
+            };
+        }
+        else
+        {
+            payload = contentBytes;
+            payloadEntryName = ContentJsonEntryName;
+            // Plaintext path: trust the supplied manifest's ContentHash. The caller
+            // built it via ManifestBuilder against the same SerializeContentBytes
+            // output (JSON is deterministic for a given DTO + JsonOptions).
+            finalManifest = manifest;
+        }
+
+        var manifestBytes = JsonSerializer.SerializeToUtf8Bytes(finalManifest, JsonOptions);
+        var ms = new MemoryStream();
+        using (var archive = new ZipArchive(ms, ZipArchiveMode.Create, leaveOpen: true))
+        {
+            WriteEntry(archive, ManifestEntryName, manifestBytes);
+            WriteEntry(archive, payloadEntryName, payload);
+        }
+
+        ms.Position = 0;
+        return ms;
+    }
+
+    public BundleManifest ReadManifest(Stream zipStream)
+    {
+        ArgumentNullException.ThrowIfNull(zipStream);
+
+        using var archive = new ZipArchive(zipStream, ZipArchiveMode.Read, leaveOpen: true);
+        var entry = archive.GetEntry(ManifestEntryName)
+            ?? throw new InvalidDataException("Bundle is missing manifest.json.");
+
+        using var es = entry.Open();
+        var manifest = JsonSerializer.Deserialize<BundleManifest>(es, JsonOptions)
+            ?? throw new InvalidDataException("manifest.json deserialized to null.");
+        return manifest;
+    }
+
+    /// <summary>
+    /// Returns the raw bytes from <c>content.enc</c> if present, otherwise from
+    /// <c>content.json</c>. The caller decrypts + JSON-deserializes via
+    /// <see cref="UnpackContent"/>.
+    /// </summary>
+    public byte[] ReadContentBytes(Stream zipStream, BundleManifest manifest)
+    {
+        ArgumentNullException.ThrowIfNull(zipStream);
+        ArgumentNullException.ThrowIfNull(manifest);
+
+        using var archive = new ZipArchive(zipStream, ZipArchiveMode.Read, leaveOpen: true);
+        // Prefer the encrypted variant when both are somehow present.
+        var entry = archive.GetEntry(ContentEncEntryName) ?? archive.GetEntry(ContentJsonEntryName)
+            ?? throw new InvalidDataException("Bundle is missing both content.enc and content.json.");
+
+        using var es = entry.Open();
+        using var ms = new MemoryStream();
+        es.CopyTo(ms);
+        return ms.ToArray();
+    }
+
+    public BundleContentDto UnpackContent(
+        byte[] contentBytes,
+        BundleManifest manifest,
+        string? passphrase,
+        BundleSecretEncryptor? encryptor)
+    {
+        ArgumentNullException.ThrowIfNull(contentBytes);
+        ArgumentNullException.ThrowIfNull(manifest);
+
+        byte[] plaintext;
+        if (manifest.Encryption is not null)
+        {
+            if (passphrase is null || encryptor is null)
+            {
+                throw new ArgumentException("Encrypted bundle requires both passphrase and encryptor.");
+            }
+            plaintext = encryptor.Decrypt(contentBytes, manifest.Encryption, passphrase);
+        }
+        else
+        {
+            plaintext = contentBytes;
+        }
+
+        var content = JsonSerializer.Deserialize<BundleContentDto>(plaintext, JsonOptions)
+            ?? throw new InvalidDataException("content payload deserialized to null.");
+        return content;
+    }
+
+    private static void WriteEntry(ZipArchive archive, string entryName, byte[] payload)
+    {
+        var entry = archive.CreateEntry(entryName, CompressionLevel.Optimal);
+        using var es = entry.Open();
+        es.Write(payload, 0, payload.Length);
+    }
+}