dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(transport): BundleExporter with audit logging

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-24 04:30:18 -04:00
parent 901d9affdf
commit 7c70ce0dbf
3 changed files with 454 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
src/ScadaLink.Transport/Export/BundleExporter.cs Normal file
View File

@@ -0,0 +1,160 @@
using System.Security.Cryptography;
using Microsoft.Extensions.Options;
using ScadaLink.Commons.Interfaces.Services;
using ScadaLink.Commons.Interfaces.Transport;
using ScadaLink.Commons.Types.Transport;
using ScadaLink.ConfigurationDatabase;
using ScadaLink.Transport.Encryption;
using ScadaLink.Transport.Serialization;
namespace ScadaLink.Transport.Export;
/// <summary>
/// Ties together the resolver, serializer, encryptor, manifest builder, and audit
/// service into a single export pipeline. Produces a ZIP-formatted bundle stream
/// and emits one append-only audit row per export — distinguishing encrypted vs
/// unencrypted runs via the <c>Action</c> column. The returned stream is positioned
/// at <c>0</c> so callers can immediately copy to a response/file.
/// </summary>
public sealed class BundleExporter : IBundleExporter
{
private readonly DependencyResolver _resolver;
private readonly EntitySerializer _entitySerializer;
private readonly ManifestBuilder _manifestBuilder;
private readonly BundleSecretEncryptor _encryptor;
private readonly BundleSerializer _bundleSerializer;
private readonly IAuditService _auditService;
private readonly ScadaLinkDbContext _dbContext;
private readonly IOptions<TransportOptions> _options;
public BundleExporter(
DependencyResolver resolver,
EntitySerializer entitySerializer,
ManifestBuilder manifestBuilder,
BundleSecretEncryptor encryptor,
BundleSerializer bundleSerializer,
IAuditService auditService,
ScadaLinkDbContext dbContext,
IOptions<TransportOptions> options)
{
_resolver = resolver ?? throw new ArgumentNullException(nameof(resolver));
_entitySerializer = entitySerializer ?? throw new ArgumentNullException(nameof(entitySerializer));
_manifestBuilder = manifestBuilder ?? throw new ArgumentNullException(nameof(manifestBuilder));
_encryptor = encryptor ?? throw new ArgumentNullException(nameof(encryptor));
_bundleSerializer = bundleSerializer ?? throw new ArgumentNullException(nameof(bundleSerializer));
_auditService = auditService ?? throw new ArgumentNullException(nameof(auditService));
_dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext));
_options = options ?? throw new ArgumentNullException(nameof(options));
}
public async Task<Stream> ExportAsync(
ExportSelection selection,
string user,
string sourceEnvironment,
string? passphrase,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(selection);
ArgumentNullException.ThrowIfNull(user);
ArgumentNullException.ThrowIfNull(sourceEnvironment);
// 1. Resolve dependencies → ResolvedExport (topologically sorted templates,
// folder chain, transitive shared-scripts/external-systems if requested).
var resolved = await _resolver.ResolveAsync(selection, cancellationToken).ConfigureAwait(false);
// 2. Convert to the wire-shaped DTO (strips EF identity, refs-by-name).
var aggregate = new EntityAggregate(
TemplateFolders: resolved.TemplateFolders,
Templates: resolved.Templates,
SharedScripts: resolved.SharedScripts,
ExternalSystems: resolved.ExternalSystems,
ExternalSystemMethods: resolved.ExternalSystemMethods,
DatabaseConnections: resolved.DatabaseConnections,
NotificationLists: resolved.NotificationLists,
SmtpConfigurations: resolved.SmtpConfigs,
ApiKeys: resolved.ApiKeys,
ApiMethods: resolved.ApiMethods);
var contentDto = _entitySerializer.ToBundleContent(aggregate);
// 3. Per-category summary counts — used for fast humanly-readable preview at import.
var summary = new BundleSummary(
Templates: resolved.Templates.Count,
TemplateFolders: resolved.TemplateFolders.Count,
SharedScripts: resolved.SharedScripts.Count,
ExternalSystems: resolved.ExternalSystems.Count,
DbConnections: resolved.DatabaseConnections.Count,
NotificationLists: resolved.NotificationLists.Count,
SmtpConfigs: resolved.SmtpConfigs.Count,
ApiKeys: resolved.ApiKeys.Count,
ApiMethods: resolved.ApiMethods.Count);
// 4. Build a TEMPLATE manifest. BundleSerializer.Pack re-stamps both
// ContentHash and EncryptionMetadata against the bytes it actually
// writes, so we only need to seed EncryptionMetadata.Iterations when
// a passphrase is supplied — Pack rebuilds salt/iv/hash internally.
var assemblyVersion = typeof(BundleExporter).Assembly.GetName().Version?.ToString() ?? "0.0.0";
EncryptionMetadata? encryptionSeed = passphrase is null
? null
: new EncryptionMetadata(
Algorithm: "AES-256-GCM",
Kdf: "PBKDF2-SHA256",
Iterations: _options.Value.Pbkdf2Iterations,
SaltB64: string.Empty,
IvB64: string.Empty);
var templateManifest = _manifestBuilder.Build(
sourceEnvironment: sourceEnvironment,
exportedBy: user,
scadaLinkVersion: assemblyVersion,
encryption: encryptionSeed,
summary: summary,
contents: resolved.ContentManifest,
// Pack re-stamps ContentHash against the bytes it actually writes
// (either fresh ciphertext or the JSON it just serialized), so the
// upstream hash here only matters for the plaintext path — Pack
// trusts the supplied hash and the serializer is deterministic.
contentBytes: _bundleSerializer.SerializeContentBytes(contentDto));
// 5. Pack the zip; with a passphrase, Pack re-encrypts and re-stamps
// EncryptionMetadata (fresh salt/iv) + ContentHash.
var zipStream = _bundleSerializer.Pack(contentDto, templateManifest, passphrase, _encryptor);
// 6. Audit — entityId is the bundle's overall SHA-256 over the zip bytes
// (opaque to caller but uniquely identifies this export). Action
// discriminates encrypted vs unencrypted runs.
var bundleHash = ComputeStreamSha256(zipStream);
await _auditService.LogAsync(
user: user,
action: passphrase is null ? "UnencryptedBundleExport" : "BundleExported",
entityType: "Bundle",
entityId: bundleHash,
entityName: sourceEnvironment,
afterState: new
{
SourceEnvironment = sourceEnvironment,
Encrypted = passphrase is not null,
ArtifactCount = resolved.ContentManifest.Count,
Summary = summary,
},
cancellationToken: cancellationToken).ConfigureAwait(false);
await _dbContext.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
zipStream.Position = 0;
return zipStream;
}
/// <summary>
/// Hashes the zip stream's bytes (resets position before + after) so the audit
/// row's <c>EntityId</c> uniquely identifies this exact bundle without leaking
/// any of the manifest's internal hashes (which describe content, not the zip).
/// </summary>
private static string ComputeStreamSha256(Stream stream)
{
stream.Position = 0;
using var sha = SHA256.Create();
var hash = sha.ComputeHash(stream);
stream.Position = 0;
return "sha256:" + Convert.ToHexString(hash).ToLowerInvariant();
}
}

12
src/ScadaLink.Transport/ServiceCollectionExtensions.cs
View File

@@ -2,8 +2,10 @@ using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Options;
using ScadaLink.Commons.Interfaces.Transport;
using ScadaLink.Transport.Encryption;
using ScadaLink.Transport.Export;
using ScadaLink.Transport.Import;
using ScadaLink.Transport.Serialization;
namespace ScadaLink.Transport;
@@ -16,7 +18,17 @@ public static class ServiceCollectionExtensions
ArgumentNullException.ThrowIfNull(services);
services.AddOptions<TransportOptions>().BindConfiguration(OptionsSection);
services.TryAddSingleton(TimeProvider.System);
// Pipeline building blocks: stateless services live as singletons; the
// resolver and exporter are scoped because they reach into per-request
// repository scopes and the scoped DbContext.
services.AddSingleton<BundleSecretEncryptor>();
services.AddSingleton<ManifestBuilder>();
services.AddSingleton<ManifestValidator>();
services.AddSingleton<BundleSerializer>();
services.AddSingleton<EntitySerializer>();
services.AddScoped<DependencyResolver>();
services.AddScoped<IBundleExporter, BundleExporter>();
services.AddSingleton<IBundleSessionStore, BundleSessionStore>();
// Remaining concrete services added in later tasks.
return services;

282
tests/ScadaLink.Transport.IntegrationTests/Export/BundleExporterTests.cs Normal file
View File

@@ -0,0 +1,282 @@
using System.Security.Cryptography;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using ScadaLink.Commons.Entities.ExternalSystems;
using ScadaLink.Commons.Entities.Notifications;
using ScadaLink.Commons.Entities.Scripts;
using ScadaLink.Commons.Entities.Templates;
using ScadaLink.Commons.Interfaces.Repositories;
using ScadaLink.Commons.Interfaces.Services;
using ScadaLink.Commons.Interfaces.Transport;
using ScadaLink.Commons.Types.Transport;
using ScadaLink.ConfigurationDatabase;
using ScadaLink.ConfigurationDatabase.Repositories;
using ScadaLink.ConfigurationDatabase.Services;
using ScadaLink.Transport;
using ScadaLink.Transport.Encryption;
using ScadaLink.Transport.Serialization;
namespace ScadaLink.Transport.IntegrationTests.Export;
/// <summary>
/// Integration tests for <see cref="ScadaLink.Transport.Export.BundleExporter"/>.
/// Builds a self-contained DI container (in-memory EF + the repositories +
/// AddTransport's pipeline) and asserts the exporter round-trips a real bundle
/// + writes the matching audit row. Using <see cref="ServiceCollection"/>
/// directly rather than <c>WebApplicationFactory</c> keeps the test focused on
/// the exporter — no HTTP, no Akka, no LDAP.
/// </summary>
public sealed class BundleExporterTests : IDisposable
{
private readonly ServiceProvider _provider;
public BundleExporterTests()
{
var services = new ServiceCollection();
// AddTransport's BindConfiguration call needs an IConfiguration in the
// container — an empty one is fine for these tests because the defaults
// baked into TransportOptions are exactly what we want.
services.AddSingleton<IConfiguration>(
new ConfigurationBuilder().AddInMemoryCollection().Build());
// In-memory EF — fresh database per test instance so seeded ids are
// predictable and the audit assertions can scan the whole table. The
// db name has to be resolved ONCE (outside the lambda) so every scope
// resolves the same underlying InMemoryStore — otherwise each scope's
// DbContext gets a new GUID and the seeded rows vanish between scopes.
var dbName = $"BundleExporterTests_{Guid.NewGuid()}";
services.AddDbContext<ScadaLinkDbContext>(opts =>
opts.UseInMemoryDatabase(dbName));
// Repositories the resolver pulls from.
services.AddScoped<ITemplateEngineRepository, TemplateEngineRepository>();
services.AddScoped<IExternalSystemRepository, ExternalSystemRepository>();
services.AddScoped<INotificationRepository, NotificationRepository>();
services.AddScoped<IInboundApiRepository, InboundApiRepository>();
// Audit pipeline — AuditService writes via the EF context + reads the
// bundle-import correlation id from the scoped context (null here, since
// export is not part of an import session).
services.AddScoped<IAuditCorrelationContext, AuditCorrelationContext>();
services.AddScoped<IAuditService, AuditService>();
// Add the transport pipeline itself.
services.AddTransport();
_provider = services.BuildServiceProvider();
}
public void Dispose() => _provider.Dispose();
[Fact]
public async Task ExportAsync_writes_audit_event_and_returns_valid_bundle()
{
// Arrange: seed two templates (one composing the other), a shared
// script referenced from the parent template, one external system, one
// notification list. Names live in the script bodies / DataSourceReference
// so the dependency resolver's substring scan picks them up.
await using (var scope = _provider.CreateAsyncScope())
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
var helper = new SharedScript("HelperFn", "return 1;");
ctx.SharedScripts.Add(helper);
var erp = new ExternalSystemDefinition("ErpSystem", "https://erp.example", "ApiKey");
ctx.ExternalSystemDefinitions.Add(erp);
var list = new NotificationList("OnCall");
ctx.NotificationLists.Add(list);
await ctx.SaveChangesAsync();
var baseTemplate = new Template("BaseDevice")
{
Description = "shared base",
};
// Attribute body references the helper + external system, so
// IncludeDependencies=true pulls them in automatically.
baseTemplate.Scripts.Add(new TemplateScript("init",
"var x = HelperFn(); ErpSystem.Call(\"x\");"));
ctx.Templates.Add(baseTemplate);
await ctx.SaveChangesAsync();
var composing = new Template("Pump")
{
Description = "composes BaseDevice",
};
ctx.Templates.Add(composing);
await ctx.SaveChangesAsync();
composing.Compositions.Add(new TemplateComposition("base")
{
TemplateId = composing.Id,
ComposedTemplateId = baseTemplate.Id,
});
await ctx.SaveChangesAsync();
}
// Act
Stream bundleStream;
await using (var scope = _provider.CreateAsyncScope())
{
var exporter = scope.ServiceProvider.GetRequiredService<IBundleExporter>();
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
var templateIds = await ctx.Templates.Select(t => t.Id).ToListAsync();
var selection = new ExportSelection(
TemplateIds: templateIds,
SharedScriptIds: Array.Empty<int>(),
ExternalSystemIds: Array.Empty<int>(),
DatabaseConnectionIds: Array.Empty<int>(),
NotificationListIds: Array.Empty<int>(),
SmtpConfigurationIds: Array.Empty<int>(),
ApiKeyIds: Array.Empty<int>(),
ApiMethodIds: Array.Empty<int>(),
IncludeDependencies: true);
bundleStream = await exporter.ExportAsync(
selection, user: "alice", sourceEnvironment: "dev",
passphrase: null, cancellationToken: CancellationToken.None);
}
// Copy to byte[] so we can re-open the zip multiple times below.
byte[] bundleBytes;
using (var ms = new MemoryStream())
{
await bundleStream.CopyToAsync(ms);
bundleBytes = ms.ToArray();
}
// Assert: non-empty, valid zip with the expected manifest + content.
Assert.NotEmpty(bundleBytes);
var serializer = _provider.GetRequiredService<BundleSerializer>();
BundleManifest manifest;
using (var ms = new MemoryStream(bundleBytes, writable: false))
{
manifest = serializer.ReadManifest(ms);
}
Assert.Equal("dev", manifest.SourceEnvironment);
Assert.Equal("alice", manifest.ExportedBy);
Assert.Null(manifest.Encryption);
Assert.Equal(2, manifest.Summary.Templates);
Assert.Equal(1, manifest.Summary.SharedScripts);
Assert.Equal(1, manifest.Summary.ExternalSystems);
byte[] rawContent;
using (var ms = new MemoryStream(bundleBytes, writable: false))
{
rawContent = serializer.ReadContentBytes(ms, manifest);
}
var content = serializer.UnpackContent(rawContent, manifest, passphrase: null, encryptor: null);
Assert.Equal(2, content.Templates.Count);
Assert.Contains(content.Templates, t => t.Name == "BaseDevice");
Assert.Contains(content.Templates, t => t.Name == "Pump");
Assert.Single(content.SharedScripts);
Assert.Equal("HelperFn", content.SharedScripts[0].Name);
Assert.Single(content.ExternalSystems);
Assert.Equal("ErpSystem", content.ExternalSystems[0].Name);
// Audit row landed with the expected shape — Action discriminates the
// unencrypted export path, EntityId is the SHA-256 of the zip bytes.
await using (var scope = _provider.CreateAsyncScope())
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
var entry = await ctx.AuditLogEntries.SingleAsync();
Assert.Equal("UnencryptedBundleExport", entry.Action);
Assert.Equal("alice", entry.User);
Assert.Equal("Bundle", entry.EntityType);
Assert.Equal("dev", entry.EntityName);
var expectedHash = "sha256:" + Convert.ToHexString(SHA256.HashData(bundleBytes))
.ToLowerInvariant();
Assert.Equal(expectedHash, entry.EntityId);
}
}
[Fact]
public async Task ExportAsync_with_passphrase_produces_encrypted_bundle()
{
// Arrange: minimal template only — we want to exercise the encryption
// path, not the dependency resolver.
await using (var scope = _provider.CreateAsyncScope())
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
ctx.Templates.Add(new Template("Solo") { Description = "alone" });
await ctx.SaveChangesAsync();
}
// Act
Stream bundleStream;
await using (var scope = _provider.CreateAsyncScope())
{
var exporter = scope.ServiceProvider.GetRequiredService<IBundleExporter>();
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
var ids = await ctx.Templates.Select(t => t.Id).ToListAsync();
var selection = new ExportSelection(
TemplateIds: ids,
SharedScriptIds: Array.Empty<int>(),
ExternalSystemIds: Array.Empty<int>(),
DatabaseConnectionIds: Array.Empty<int>(),
NotificationListIds: Array.Empty<int>(),
SmtpConfigurationIds: Array.Empty<int>(),
ApiKeyIds: Array.Empty<int>(),
ApiMethodIds: Array.Empty<int>(),
IncludeDependencies: true);
bundleStream = await exporter.ExportAsync(
selection, user: "bob", sourceEnvironment: "stg",
passphrase: "correct horse battery staple",
cancellationToken: CancellationToken.None);
}
byte[] bundleBytes;
using (var ms = new MemoryStream())
{
await bundleStream.CopyToAsync(ms);
bundleBytes = ms.ToArray();
}
// Assert: manifest carries fresh encryption metadata; wrong passphrase
// throws (AES-GCM tag mismatch); audit action is "BundleExported".
var serializer = _provider.GetRequiredService<BundleSerializer>();
var encryptor = _provider.GetRequiredService<BundleSecretEncryptor>();
BundleManifest manifest;
byte[] rawContent;
using (var ms = new MemoryStream(bundleBytes, writable: false))
{
manifest = serializer.ReadManifest(ms);
}
using (var ms = new MemoryStream(bundleBytes, writable: false))
{
rawContent = serializer.ReadContentBytes(ms, manifest);
}
Assert.NotNull(manifest.Encryption);
Assert.Equal("AES-256-GCM", manifest.Encryption!.Algorithm);
Assert.False(string.IsNullOrEmpty(manifest.Encryption.SaltB64));
Assert.False(string.IsNullOrEmpty(manifest.Encryption.IvB64));
// Wrong passphrase fails AES-GCM tag verification — the runtime throws
// the more specific AuthenticationTagMismatchException (a CryptographicException
// subclass on .NET 10), so ThrowsAny is correct here.
Assert.ThrowsAny<CryptographicException>(() =>
serializer.UnpackContent(rawContent, manifest, "wrong", encryptor));
// Right passphrase unpacks back to the seeded template.
var content = serializer.UnpackContent(
rawContent, manifest, "correct horse battery staple", encryptor);
Assert.Single(content.Templates);
Assert.Equal("Solo", content.Templates[0].Name);
await using (var scope = _provider.CreateAsyncScope())
{
var ctx = scope.ServiceProvider.GetRequiredService<ScadaLinkDbContext>();
var entry = await ctx.AuditLogEntries.SingleAsync();
Assert.Equal("BundleExported", entry.Action);
Assert.Equal("bob", entry.User);
Assert.Equal("stg", entry.EntityName);
}
}
}