feat(transport): ManifestBuilder + ManifestValidator with schema-version gating

src/ScadaLink.Transport/Serialization/ManifestBuilder.cs

@@ -0,0 +1,47 @@
+using System.Security.Cryptography;
+using ScadaLink.Commons.Types.Transport;
+
+namespace ScadaLink.Transport.Serialization;
+
+/// <summary>
+/// Builds a <see cref="BundleManifest"/> for a freshly serialized bundle.
+/// Stamps the current format/schema version, captures the SHA-256 hash of the
+/// raw (post-encryption) content bytes, and copies through the supplied summary
+/// and content entries verbatim.
+/// </summary>
+public sealed class ManifestBuilder
+{
+    public const int CurrentBundleFormatVersion = 1;
+    public const string CurrentSchemaVersion = "1.0";
+
+    public BundleManifest Build(
+        string sourceEnvironment,
+        string exportedBy,
+        string scadaLinkVersion,
+        EncryptionMetadata? encryption,
+        BundleSummary summary,
+        IReadOnlyList<ManifestContentEntry> contents,
+        byte[] contentBytes)
+    {
+        ArgumentNullException.ThrowIfNull(sourceEnvironment);
+        ArgumentNullException.ThrowIfNull(exportedBy);
+        ArgumentNullException.ThrowIfNull(scadaLinkVersion);
+        ArgumentNullException.ThrowIfNull(summary);
+        ArgumentNullException.ThrowIfNull(contents);
+        ArgumentNullException.ThrowIfNull(contentBytes);
+
+        var contentHash = "sha256:" + Convert.ToHexString(SHA256.HashData(contentBytes)).ToLowerInvariant();
+
+        return new BundleManifest(
+            BundleFormatVersion: CurrentBundleFormatVersion,
+            SchemaVersion: CurrentSchemaVersion,
+            CreatedAtUtc: DateTimeOffset.UtcNow,
+            SourceEnvironment: sourceEnvironment,
+            ExportedBy: exportedBy,
+            ScadaLinkVersion: scadaLinkVersion,
+            ContentHash: contentHash,
+            Encryption: encryption,
+            Summary: summary,
+            Contents: contents);
+    }
+}

src/ScadaLink.Transport/Serialization/ManifestValidator.cs

@@ -0,0 +1,50 @@
+using System.Security.Cryptography;
+using ScadaLink.Commons.Types.Transport;
+
+namespace ScadaLink.Transport.Serialization;
+
+/// <summary>
+/// Outcome of validating a <see cref="BundleManifest"/> against the supplied
+/// raw content bytes. Distinct values let the importer surface a precise
+/// rejection reason to the operator.
+/// </summary>
+public enum ManifestValidationResult
+{
+    Ok,
+    UnsupportedFormatVersion,
+    ContentHashMismatch,
+    MalformedManifest
+}
+
+/// <summary>
+/// Inspects a deserialized manifest plus the raw content bytes recovered from
+/// the bundle ZIP and reports the first integrity failure (or <see cref="ManifestValidationResult.Ok"/>).
+/// </summary>
+public sealed class ManifestValidator
+{
+    public ManifestValidationResult Validate(BundleManifest manifest, byte[] contentBytes)
+    {
+        if (manifest is null || contentBytes is null)
+        {
+            return ManifestValidationResult.MalformedManifest;
+        }
+
+        if (string.IsNullOrEmpty(manifest.SourceEnvironment) || manifest.Contents is null)
+        {
+            return ManifestValidationResult.MalformedManifest;
+        }
+
+        if (manifest.BundleFormatVersion != ManifestBuilder.CurrentBundleFormatVersion)
+        {
+            return ManifestValidationResult.UnsupportedFormatVersion;
+        }
+
+        var expected = "sha256:" + Convert.ToHexString(SHA256.HashData(contentBytes)).ToLowerInvariant();
+        if (!string.Equals(expected, manifest.ContentHash, StringComparison.Ordinal))
+        {
+            return ManifestValidationResult.ContentHashMismatch;
+        }
+
+        return ManifestValidationResult.Ok;
+    }
+}