feat(transport): BundleSerializer ZIP packer/reader
This commit is contained in:
Joseph Doherty
178
src/ScadaLink.Transport/Serialization/BundleSerializer.cs
Normal file
178
src/ScadaLink.Transport/Serialization/BundleSerializer.cs
Normal file
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,126 @@
|
||||
using System.IO.Compression;
|
||||
using System.Security.Cryptography;
|
||||
using ScadaLink.Commons.Types.Transport;
|
||||
using ScadaLink.Transport.Encryption;
|
||||
using ScadaLink.Transport.Serialization;
|
||||
|
||||
namespace ScadaLink.Transport.Tests.Serialization;
|
||||
|
||||
public sealed class BundleSerializerTests
|
||||
{
|
||||
private const int TestIterations = 10_000;
|
||||
|
||||
private static BundleContentDto SampleContent() => new(
|
||||
TemplateFolders: new[] { new TemplateFolderDto("Root", ParentName: null, SortOrder: 0) },
|
||||
Templates: Array.Empty<TemplateDto>(),
|
||||
SharedScripts: new[] { new SharedScriptDto("util", "return 42;", ParameterDefinitions: null, ReturnDefinition: null) },
|
||||
ExternalSystems: Array.Empty<ExternalSystemDto>(),
|
||||
DatabaseConnections: Array.Empty<DatabaseConnectionDto>(),
|
||||
NotificationLists: Array.Empty<NotificationListDto>(),
|
||||
SmtpConfigs: Array.Empty<SmtpConfigDto>(),
|
||||
ApiKeys: Array.Empty<ApiKeyDto>(),
|
||||
ApiMethods: Array.Empty<ApiMethodDto>());
|
||||
|
||||
private static BundleManifest BuildManifestFor(byte[] contentBytes, EncryptionMetadata? encryption = null) =>
|
||||
new ManifestBuilder().Build(
|
||||
sourceEnvironment: "test-env",
|
||||
exportedBy: "tester",
|
||||
scadaLinkVersion: "1.0.0",
|
||||
encryption: encryption,
|
||||
summary: new BundleSummary(0, 1, 1, 0, 0, 0, 0, 0, 0),
|
||||
contents: Array.Empty<ManifestContentEntry>(),
|
||||
contentBytes: contentBytes);
|
||||
|
||||
[Fact]
|
||||
public void Pack_emits_manifest_and_content_json_when_no_passphrase()
|
||||
{
|
||||
var sut = new BundleSerializer();
|
||||
var content = SampleContent();
|
||||
var contentJson = sut.SerializeContentBytes(content);
|
||||
var manifest = BuildManifestFor(contentJson);
|
||||
|
||||
using var stream = sut.Pack(content, manifest, passphrase: null, encryptor: null);
|
||||
|
||||
using var archive = new ZipArchive(stream, ZipArchiveMode.Read, leaveOpen: true);
|
||||
Assert.NotNull(archive.GetEntry("manifest.json"));
|
||||
Assert.NotNull(archive.GetEntry("content.json"));
|
||||
Assert.Null(archive.GetEntry("content.enc"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Pack_emits_manifest_and_content_enc_when_passphrase_supplied()
|
||||
{
|
||||
var sut = new BundleSerializer();
|
||||
var encryptor = new BundleSecretEncryptor();
|
||||
var content = SampleContent();
|
||||
var contentJson = sut.SerializeContentBytes(content);
|
||||
var (cipher, meta) = encryptor.Encrypt(contentJson, "pass", TestIterations);
|
||||
var manifest = BuildManifestFor(cipher, encryption: meta);
|
||||
|
||||
using var stream = sut.Pack(content, manifest, passphrase: "pass", encryptor: encryptor);
|
||||
|
||||
using var archive = new ZipArchive(stream, ZipArchiveMode.Read, leaveOpen: true);
|
||||
Assert.NotNull(archive.GetEntry("manifest.json"));
|
||||
Assert.Null(archive.GetEntry("content.json"));
|
||||
Assert.NotNull(archive.GetEntry("content.enc"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Roundtrip_through_temp_stream_recovers_identical_content()
|
||||
{
|
||||
var sut = new BundleSerializer();
|
||||
var content = SampleContent();
|
||||
var contentJson = sut.SerializeContentBytes(content);
|
||||
var manifest = BuildManifestFor(contentJson);
|
||||
|
||||
using var stream = sut.Pack(content, manifest, passphrase: null, encryptor: null);
|
||||
|
||||
stream.Position = 0;
|
||||
var readManifest = sut.ReadManifest(stream);
|
||||
stream.Position = 0;
|
||||
var contentBytes = sut.ReadContentBytes(stream, readManifest);
|
||||
var unpacked = sut.UnpackContent(contentBytes, readManifest, passphrase: null, encryptor: null);
|
||||
|
||||
Assert.Equal(manifest.ContentHash, readManifest.ContentHash);
|
||||
Assert.Single(unpacked.TemplateFolders);
|
||||
Assert.Equal("Root", unpacked.TemplateFolders[0].Name);
|
||||
var shared = Assert.Single(unpacked.SharedScripts);
|
||||
Assert.Equal("util", shared.Name);
|
||||
Assert.Equal("return 42;", shared.Code);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ReadManifest_throws_when_zip_missing_manifest_json()
|
||||
{
|
||||
var sut = new BundleSerializer();
|
||||
using var ms = new MemoryStream();
|
||||
using (var archive = new ZipArchive(ms, ZipArchiveMode.Create, leaveOpen: true))
|
||||
{
|
||||
var entry = archive.CreateEntry("garbage.txt");
|
||||
using var es = entry.Open();
|
||||
es.Write(new byte[] { 1, 2, 3 });
|
||||
}
|
||||
ms.Position = 0;
|
||||
|
||||
Assert.Throws<InvalidDataException>(() => sut.ReadManifest(ms));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void UnpackContent_throws_CryptographicException_on_wrong_passphrase()
|
||||
{
|
||||
var sut = new BundleSerializer();
|
||||
var encryptor = new BundleSecretEncryptor();
|
||||
var content = SampleContent();
|
||||
var contentJson = sut.SerializeContentBytes(content);
|
||||
var (cipher, meta) = encryptor.Encrypt(contentJson, "right", TestIterations);
|
||||
var manifest = BuildManifestFor(cipher, encryption: meta);
|
||||
|
||||
using var stream = sut.Pack(content, manifest, passphrase: "right", encryptor: encryptor);
|
||||
stream.Position = 0;
|
||||
var readManifest = sut.ReadManifest(stream);
|
||||
stream.Position = 0;
|
||||
var contentBytes = sut.ReadContentBytes(stream, readManifest);
|
||||
|
||||
Assert.ThrowsAny<CryptographicException>(() => sut.UnpackContent(contentBytes, readManifest, "wrong", encryptor));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user