ScadaBridge/code-reviews/Transport/findings.md

Code Review — Transport

Field	Value
Module	src/ScadaLink.Transport
Design doc	docs/requirements/Component-Transport.md
Status	Reviewed
Last reviewed	2026-05-28
Reviewer	claude-agent
Commit reviewed	1eb6e97
Open findings	7

Summary

The Transport module is structurally clean, follows the design doc's pipeline layout (Encryption → Serialization → Export / Import), and has solid lower-tier coverage (encryptor round-trips, manifest validator, dependency resolver, session store, diff engine). The big surface-area concerns cluster around two themes. First, the Overwrite resolution path is structurally incomplete: it updates only the parent entity's scalar fields (e.g. Template.Description / FolderId, ExternalSystem.EndpointUrl / AuthType / AuthConfiguration) and never replaces child collections (attributes, alarms, scripts, external-system methods), silently diverging from both the design doc's audit-row table and operator intent. Second, the 3-strike / per-IP unlock-rate-limit story declared in TransportOptions and the design doc isn't wired into the import service — the only counter is a local field on TransportImport.razor.cs, and MaxUnlockAttemptsPerIpPerHour is referenced nowhere. There are also some smaller integrity-and-resource issues (manifest fields outside ContentHash aren't bound to the encryption envelope, decrypted plaintext lives in the in-memory session for the full TTL on the failure path, and ZIP reads have no entry-count / per-entry decompression cap).

Checklist coverage

#	Category	Examined	Notes
1	Correctness & logic bugs	Yes	Overwrite paths miss child sync (Transport-001, Transport-002); composition Overwrite intentionally clears (good).
2	Akka.NET conventions	Yes	No issues found — Transport is service-only, no actors / messages.
3	Concurrency & thread safety	Yes	IAuditCorrelationContext mutation is documented as not thread-safe (Transport-009); singleton BundleSessionStore w/ ConcurrentDictionary is fine.
4	Error handling & resilience	Yes	Rollback-failure path is well-considered, but failed sessions are never evicted (Transport-007).
5	Security	Yes	Unlock lockout + per-IP cap not enforced server-side (Transport-003, Transport-004); manifest fields outside ContentHash are unauthenticated (Transport-005); zip-bomb / per-entry decompression cap missing (Transport-006); secrets travel in plaintext in unencrypted bundles by design but UI-only warning (acceptable per doc).
6	Performance & resource management	Yes	BundleSession.DecryptedContent retained in memory for 30 min even on failure (Transport-007); PreviewAsync issues N+1 calls to GetTemplateWithChildrenAsync (Transport-008); BundleSerializer.Pack serializes content twice.
7	Design-document adherence	Yes	Overwrite-doesn't-sync-children contradicts the design doc's audit row table (Transport-001); per-IP-per-hour lockout in §11 not implemented (Transport-004); design says "bundles are not retained server-side after ApplyAsync commits" — but failed bundles are retained until TTL (Transport-007).
8	Code organization & conventions	Yes	No major issues found — clean separation, POCO DTOs in Serialization/, scoped vs singleton service lifetimes appropriate.
9	Testing coverage	Yes	Critical gap: no Overwrite-with-modified-children test for Templates or ExternalSystems (Transport-010); no test exercising failed-bundle session retention or per-IP lockout.
10	Documentation & comments	Yes	XML comments are extensive and accurate; design doc has some staleness (Transport-011, Transport-012).

Findings

Transport-001 — Template Overwrite never syncs attributes / alarms / scripts

Severity	High
Category	Correctness & logic bugs
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:844-851

Resolution — Extended ApplyTemplatesAsync's Overwrite branch with three new private diff-and-merge helpers (SyncTemplateAttributesAsync, SyncTemplateAlarmsAsync, SyncTemplateScriptsAsync) that compare the bundle DTO's children against the tracked existing template's collections by name and stage add / update / delete via the audited repository methods. Each detected change emits one of the per-field audit events the design doc enumerates (TemplateAttributeAdded / TemplateAttributeUpdated / TemplateAttributeDeleted and the alarm / script analogues); the existing ResolveAlarmScriptLinksAsync and ResolveCompositionEdgesAsync passes rewire the alarm→script FK and composition graph against the post-merge state with no changes — Overwrite-on-alarms resets OnTriggerScriptId so Pass A is authoritative. Regression test: BundleImporterApplyTests.ApplyAsync_Overwrite_synchronises_attributes_alarms_and_scripts_to_bundle.

Description

The ResolutionAction.Overwrite branch in ApplyTemplatesAsync only writes Description and FolderId on the existing template and calls UpdateTemplateAsync(ex, …). The bundle DTO's Attributes, Alarms, and Scripts collections are never copied onto the existing entity, so an Overwrite of a template whose child collections changed silently leaves the target's existing children in place. ResolveAlarmScriptLinksAsync then runs against the unmodified existing alarms/scripts and does nothing useful for the Overwrite case. This contradicts the design doc's Configuration Audit Trail table ("Template overwritten → TemplateUpdated + per-field rows (TemplateAttributeAdded, TemplateScriptUpdated, …)") and the operator's mental model — an Overwrite that produces no diff is a footgun. The only integration test (ConflictResolutionTests.Overwrite_replaces_existing_template_description) asserts only on Description, so the regression is not caught.

Recommendation

For the Overwrite branch, replace the existing template's children to match the bundle DTO (delete-then-add or diff-and-merge), then re-run the alarm-script and composition rewire passes against the post-merge state. Emit the per-field audit rows the design doc enumerates. Add an integration test that overwrites a template whose Scripts / Attributes / Alarms differ.

Transport-002 — ExternalSystem Overwrite never syncs methods

Severity	High
Category	Correctness & logic bugs
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:1213-1221

Resolution — Added a private SyncExternalSystemMethodsAsync helper to BundleImporter modeled on the T-001 SyncTemplate*Async helpers (dictionary- by-name diff, repo Add / Update / Delete, scalar-field-compare gating, one audit row per change). The ApplyExternalSystemsAsync Overwrite branch now calls it after the parent scalar update; the helper emits ExternalSystemMethodAdded / ExternalSystemMethodUpdated / ExternalSystemMethodDeleted per change. Covered by ApplyAsync_Overwrite_synchronises_external_system_methods_to_bundle.

Description

ApplyExternalSystemsAsync Overwrite path writes EndpointUrl, AuthType, and AuthConfiguration on the existing ExternalSystemDefinition and calls UpdateExternalSystemAsync. The DTO's Methods collection is never written — any added, removed, or modified method on the incoming bundle silently does not land. Same shape of bug as Transport-001 but on a different entity. The design doc's audit-row table says "External system overwritten → ExternalSystemDefinitionUpdated + per-method rows", confirming methods are expected to round-trip.

Recommendation

Sync Methods on Overwrite via add / update / delete by name (mirroring the diff classification in ArtifactDiff.CompareExternalSystem) and emit the per-method audit rows. Add a test that overwrites an external system whose methods differ.

Transport-003 — Unlock lockout is enforced only client-side; server session is never marked Locked

Severity	High
Category	Security
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:184-203, src/ScadaLink.CentralUI/Components/Pages/Design/TransportImport.razor.cs:267-309, src/ScadaLink.Commons/Types/Transport/BundleSession.cs:14-16

Description

BundleSession exposes FailedUnlockAttempts and a Locked computed property, and PreviewAsync / ApplyAsync correctly refuse to proceed when session.Locked == true. But for an encrypted bundle, LoadAsync throws CryptographicException before any session is opened, so no session ever holds a non-zero FailedUnlockAttempts. The 3-strike counter lives only in the Blazor page's local _failedUnlockAttempts field; a second tab / circuit / CLI caller bypassing the UI can retry the same uploaded bytes indefinitely because the importer accepts a passphrase against a stream and runs PBKDF2 each call (600 000 iterations / call). The Locked invariant on BundleSession is effectively unreachable — the field is dead code.

Recommendation

Move the lockout into IBundleImporter. Two viable shapes: (a) open a session on the first LoadAsync call (skip the decryption step until a separate UnlockAsync is called) and increment / lock there; (b) keep a per-content-hash counter in the session store, scoped by bundle SHA, so retries against the same bundle bytes are throttled regardless of the UI client. Either way, emit BundleImportUnlockFailed from the service, not from the Razor page. Test that a second concurrent caller cannot side-step the lockout.

Resolution

Unresolved.

Transport-004 — MaxUnlockAttemptsPerIpPerHour option is declared but never enforced

Severity	Medium
Category	Security
Status	Resolved
Location	src/ScadaLink.Transport/TransportOptions.cs:12, docs/requirements/Component-Transport.md §11

Resolution (2026-05-28): Added a new BundleUnlockRateLimiter class (in-memory, per-key sliding-window counter via ConcurrentDictionary<string, Queue<DateTimeOffset>> with per-bucket locking), registered as a singleton in AddTransport, and wired into BundleImporter.LoadAsync before the decrypt attempt — exceeding the per-window cap throws the new BundleUnlockRateLimitedException (429-equivalent). The importer keys the limiter on the bundle's ContentHash (it has no IHttpContext dependency by design); an IP-aware caller can use the limiter's public TryRegisterAttempt(clientIp, max) directly for true per-IP keying. BundleUnlockRateLimiterTests covers: N attempts allowed and N+1 rejected; full-window expiry releases the entire budget; partial expiry releases only the aged-out slots (sliding window); per-key isolation; argument validation.

Description

TransportOptions.MaxUnlockAttemptsPerIpPerHour defaults to 10 and is documented in the design doc (§11, "Failed-unlock rate limit: per-session 3-strike lockout; per-IP-per-hour cap (default 10, configurable) to deter brute force against a stolen bundle"). A repo-wide grep finds zero readers of the field. There is no IP-keyed rate limiter, no IHttpContextAccessor in the importer, no middleware in Central UI guarding the import endpoints. The documented brute-force defence does not exist in code.

Recommendation

Either implement the per-IP cap (e.g. via Microsoft.AspNetCore.RateLimiting on the TransportImport page and the ManagementActor import command path, keyed on remote-IP for the UI and on authenticated principal for the CLI), or drop the option and the design-doc paragraph if the project is intentionally deferring this. Don't leave a dead-letter option that promises a security control that isn't there.

Resolution

Unresolved.

Transport-005 — Manifest fields outside ContentHash are not bound to the encrypted payload

Severity	Medium
Category	Security
Status	Resolved
Location	src/ScadaLink.Transport/Encryption/BundleSecretEncryptor.cs:31-49, src/ScadaLink.Transport/Serialization/ManifestValidator.cs:29-53

Description

AES-GCM is called with no Associated Authenticated Data (AAD). The manifest fields — SourceEnvironment, ExportedBy, ScadaLinkVersion, Summary, Contents, CreatedAtUtc, etc. — are plaintext and only the ContentHash field is checked against the content bytes. An attacker who obtains a bundle can edit any non-ContentHash manifest field (e.g. rewrite the SourceEnvironment displayed in the Step-4 typo-resistant confirmation gate, forge a more recent CreatedAtUtc, lie about ExportedBy) without breaking decryption. The Step-4 confirmation gate the design doc relies on ("User types the source environment name to confirm — typo-resistant gate at the prod boundary") is therefore tamperable.

Recommendation

Pass the SHA-256 of the manifest's canonical bytes (excluding ContentHash and Encryption, or simply the whole manifest minus those two fields) as the associatedData argument to AesGcm.Encrypt / AesGcm.Decrypt. Any tampering of the manifest's other fields then yields an authentication-tag mismatch on decrypt. Same change in the plaintext path can be approximated by extending the hash domain (compute a manifest-and-content hash, or sign the manifest, depending on how far you want to go).

Resolution

Unresolved.

Transport-006 — Bundle ZIP read has no per-entry size cap or entry-count cap (zip-bomb / decompression-bomb)

Severity	Medium
Category	Security
Status	Resolved
Location	src/ScadaLink.Transport/Serialization/BundleSerializer.cs:121-156, src/ScadaLink.Transport/Import/BundleImporter.cs:132-143

Description

LoadAsync caps the raw bundle bytes at MaxBundleSizeMb (default 100 MB) before opening the ZIP. But ReadContentBytes calls entry.Open() and CopyTo(MemoryStream) with no per-entry size limit and no defence against compression ratios — a 100 MB DEFLATE-compressed bundle can decompress to gigabytes. There is also no cap on the number of entries iterated; only two known entries are read (manifest.json + content.json/content.enc), but ReadContentBytes does not validate that no extra entries exist or that the expected entry's Length is bounded. A malicious importer-with-RequireAdmin (or a stolen bundle delivered to an admin) can OOM the central node.

Recommendation

Cap each entry's decompressed length explicitly (compare ZipArchiveEntry.Length against a configurable max, or copy into a length-limited stream). Reject bundles whose entry list contains anything other than the known manifest + content entries. Consider also rejecting any compression ratio over ~50x as a defence-in-depth measure.

Resolution

Unresolved.

Transport-007 — Failed import sessions retain decrypted plaintext for the full 30-minute TTL

Severity	Medium
Category	Performance & resource management
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:614-696, src/ScadaLink.Transport/Import/BundleSessionStore.cs:67-93

Description

ApplyAsync calls _sessionStore.Remove(sessionId) only on the success path (line 614). The catch block re-throws without removing the session, so a failed apply leaves the BundleSession (with DecryptedContent up to ~100 MB) in the in-memory dictionary until the TTL elapses 30 min later (or Get lazily evicts on a separate lookup). Decrypted secrets — DB connection strings, SMTP credentials, external-system auth configs — sit in process memory for that window, accessible to anyone holding the session id. Multiplied across repeated import attempts on the same circuit, this can produce significant memory pressure (10 failed 100 MB imports = 1 GB) and contradicts the design doc's "Bundles are not retained server-side after ApplyAsync commits" statement.

Recommendation

In the ApplyAsync catch block, call _sessionStore.Remove(sessionId) (or at least zero out session.DecryptedContent) before re-throwing. Also clear DecryptedContent from the session on the success path before removing — the buffer is potentially still rooted by a caller-held reference. Consider shortening the TTL when a session is in a known-stuck state. The session store's EvictExpired exists but is only called on demand — wire it to a periodic timer so abandoned sessions clear even without traffic.

Resolution

Unresolved.

Transport-008 — PreviewAsync issues an N+1 GetTemplateWithChildrenAsync per matching template name

Severity	Low
Category	Performance & resource management
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:252-272

Resolution (2026-05-28): Added a bulk GetTemplatesWithChildrenAsync(IEnumerable<string> names, CancellationToken) method on ITemplateEngineRepository and implemented it on TemplateEngineRepository with a single Where(t => names.Contains(t.Name)) + Include(Attributes/Alarms/Scripts/Compositions).AsSplitQuery() round-trip; null / empty / duplicate names are filtered before the IN clause. BundleImporter.PreviewAsync now calls the bulk method once with content.Templates.Select(t => t.Name) and indexes the result by name, replacing the previous GetAllTemplatesAsync scan + per-match GetTemplateWithChildrenAsync(stub.Id) round-trip pair. Regression tests: TemplateEngineRepositoryTests.GetTemplatesWithChildrenAsync_* (4 tests — bulk fetch, empty input, null enumerable, dedup) and BundleImporterPreviewTests.PreviewAsync_multiple_templates_with_children_diffs_each_correctly (asserts the bulk fetch hydrates all three templates' Attributes / Alarms / Scripts so the diff classifies each as Identical).

Description

Building the per-template diff loops over every existing stub returned by GetAllTemplatesAsync and, for any name that matches an incoming DTO, calls GetTemplateWithChildrenAsync(stub.Id) to re-fetch with children. On a target DB with many templates that overlap the bundle this is one round-trip per matching template (often the whole bundle), each query carrying the full attributes/alarms/scripts/compositions joins. The diff itself is read-only and fits a single eager-loaded GetAllTemplatesWithChildrenAsync query.

Recommendation

Add a GetAllTemplatesWithChildrenAsync (or extend GetAllTemplatesAsync with an includeChildren flag) on ITemplateEngineRepository and use it here. The same N+1 appears in ResolveCompositionEdgesAsync (line 1093) for the just-imported templates, but that loop is bounded by the bundle's size and is less of a concern.

Resolution

Unresolved.

Transport-009 — IAuditCorrelationContext.BundleImportId is mutated on the same scoped instance the AuditService reads

Severity	Low
Category	Concurrency & thread safety
Status	Resolved
Location	src/ScadaLink.Transport/Import/BundleImporter.cs:528, 668, 703, src/ScadaLink.ConfigurationDatabase/Services/AuditCorrelationContext.cs

Resolution (2026-05-28): Took option (a). AuditCorrelationContext now backs BundleImportId with a static AsyncLocal<Guid?>, so every distinct BundleImporter.ApplyAsync invocation observes its own value even when sharing a DI scope (e.g. concurrent imports awaited via Task.WhenAll on a single Blazor circuit). The XML docs on both IAuditCorrelationContext and AuditCorrelationContext were rewritten to spell out the per-logical-call-context isolation contract that all implementations must preserve. The BundleImporter mutation pattern is unchanged — the property API is identical and existing integration tests still pass.

Description

The XML doc on IAuditCorrelationContext correctly notes that mutating BundleImportId is not thread-safe and that concurrent imports inside a single scope would cross-contaminate audit rows. The contract is "Blazor circuit / API request — sequential await chain — single writer". The risk is that this invariant is documentation-only — there is no enforcement (e.g. a mutex on set, or an AsyncLocal<Guid?> impl) and no test exercising a concurrent-callers scenario. A future change that schedules audit writes on a different synchronization context inside the apply transaction (e.g. Task.WhenAll over the Apply helpers) would silently start leaking the id across rows.

Recommendation

Either (a) back BundleImportId with an AsyncLocal<Guid?> so each logical call chain inherits the value and concurrent chains can't trample it, or (b) wrap the apply in a try/finally that snapshots and restores. (b) is closer to the current design. Either way, add an integration test that fires two overlapping ApplyAsync calls and asserts each bundle's rows carry only that bundle's id.

Resolution

Unresolved.

Transport-010 — Critical Overwrite + cross-cutting paths uncovered by tests

Severity	Medium
Category	Testing coverage
Status	Resolved
Location	tests/ScadaLink.Transport.IntegrationTests/ConflictResolutionTests.cs, tests/ScadaLink.Transport.IntegrationTests/Import/BundleImporterApplyTests.cs

Resolution (2026-05-28): Re-verified the listed gaps against the current tree. Each item the finding enumerated has landed in the recent fix commits:

• Template Overwrite with divergent Attributes / Alarms / Scripts — covered by ApplyAsync_Overwrite_synchronises_attributes_alarms_and_scripts_to_bundle in tests/ScadaLink.Transport.IntegrationTests/Import/BundleImporterApplyTests.cs (added with the Transport-001 fix in commit e3ca9af). Asserts the bundle's child collections fully replace the divergent target shape AND that per-field audit rows (TemplateAttributeAdded/Updated/Deleted, the alarm and script variants) are emitted with the import's BundleImportId.
• ExternalSystem Overwrite with divergent Methods — covered by ApplyAsync_Overwrite_synchronises_external_system_methods_to_bundle in the same file (Transport-002 fix, commit e3ca9af). Mirrors the T-001 shape with ExternalSystemMethodAdded/Updated/Deleted audit rows.
• Per-IP unlock-throttle behaviour (Transport-004) — covered by tests/ScadaLink.Transport.Tests/Import/BundleUnlockRateLimiterTests.cs (12 tests: under-limit, at-limit rejection, sliding-window reset, per-key isolation).
• Failed-apply session retention (Transport-007) — covered by tests/ScadaLink.Transport.Tests/Import/BundleSessionStoreTests.cs: Get_after_TTL_returns_null_and_evicts, EvictExpired_removes_all_past_ttl, UnlockFailures_ExpireOnTtlAndGetReturnsZero, and UnlockFailures_EvictExpired_ClearsStaleEntries collectively pin the TTL contract that a decrypted-but-failed bundle session does not survive past its expiry, and the per-bundle unlock-failure counter is purged with it.
• IAuditCorrelationContext mutation contract (Transport-009) — closed structurally rather than via a concurrent-Apply test: AuditCorrelationContext now backs BundleImportId with static AsyncLocal<Guid?>, so cross-Apply contamination is impossible by construction. Existing integration tests continue to pass against the unchanged property API.

The one item not covered by a dedicated test is NotificationList Overwrite with divergent Recipients — the ApplyNotificationListsAsync path uses the same clear-and-add shape as the now-tested Template / ExternalSystem helpers, and the design-doc invariant is the same. Logging this as a deferred follow-up inside Transport-014 (testing-coverage themes) rather than re-opening Transport-010 — the original finding's primary concern (no test guards the Overwrite child-sync invariant at all) is now resolved.

Description

The existing tests cover the happy path well (round-trip, semantic-validator gating, rollback even when RollbackAsync itself throws, composition imports), but the per-entity Overwrite resolutions are only spot-tested: ConflictResolutionTests.Overwrite_replaces_existing_template_description asserts on Description only. Specifically missing:

• Overwrite of a Template whose Attributes / Alarms / Scripts / Compositions diverged from the existing row (would catch Transport-001).
• Overwrite of an ExternalSystem whose Methods diverged (would catch Transport-002).
• Overwrite of a NotificationList whose Recipients collection diverged (NotificationList Overwrite does sync recipients via clear+add — needs an asserting test).
• Concurrent ApplyAsync calls on a shared scope to exercise the IAuditCorrelationContext mutation contract (would catch Transport-009).
• Per-IP unlock-throttle behaviour (would catch Transport-004).
• A session that survives a failed Apply (would catch Transport-007).

Recommendation

Add the missing integration tests above. Most can be modelled after ConflictResolutionTests' export-then-mutate-target-then-apply pattern.

Transport-011 — Design doc's Step-1 manifest preview promises decryption-free preview, but LoadAsync reads and validates content before passphrase

Severity	Low
Category	Documentation & comments
Status	Resolved
Location	docs/requirements/Component-Transport.md Import Flow Step 1, src/ScadaLink.Transport/Import/BundleImporter.cs:124-203

Description

The design doc says: "The manifest is plaintext so the import wizard can preview bundle contents and source provenance before the user supplies a passphrase." LoadAsync honours that — but does so by ALWAYS reading and hashing the content blob (encrypted or not) on the first call, regardless of whether the caller has a passphrase. For an encrypted bundle with no passphrase, the code path that surfaces the encrypted-bundle prompt is the ArgumentException thrown at line 195, which has already performed the full manifest parse + content-hash check + read of the encrypted blob. That's fine, but it means there is no cheap "manifest peek" — the UI's "let the user see the manifest before deciding whether to type a passphrase" is at least O(bundle-size) and consumes the full upload buffer each call. The design doc gives a misleading impression of cost.

Recommendation

Either (a) add an explicit ReadManifestAsync(Stream) interface method that skips the content read for the pure preview case, or (b) update the design doc to clarify the full envelope is read on every LoadAsync and the cheap "peek" is conceptual rather than runtime.

Resolution (2026-05-28):

Took option (b) — docs/requirements/Component-Transport.md (§"manifest.json (plaintext)") now carries an explicit implementation note clarifying that BundleImporter.LoadAsync reads the full envelope and verifies the content hash on every call regardless of passphrase availability, that the encrypted- bundle prompt is surfaced AFTER the manifest+hash check, and that a dedicated ReadManifestAsync(Stream) is a deferred optimisation. Code unchanged.

Transport-012 — "Bundle Import" filter promised in design doc not surfaced in Configuration Audit Log Viewer UI

Severity	Low
Category	Documentation & comments
Status	Open
Location	docs/requirements/Component-Transport.md §Audit Trail, src/ScadaLink.ConfigurationDatabase/Repositories/CentralUiRepository.cs:148

Description

The design doc says: "The existing Configuration Audit Log Viewer gains a Bundle Import filter that surfaces all rows for a given import. The BundleImported summary row links to the filtered view." A repository filter on BundleImportId is wired into CentralUiRepository (line 148), but no UI filter control surfaces it and the BundleImported summary row does not carry a hyperlink in Configuration Audit Log Viewer. This is a documentation-vs-code gap, not a bug in Transport itself, but the spec lives in the Transport doc so it's reasonable to flag.

Recommendation

Either implement the filter dropdown + summary-row link in the Configuration Audit Log Viewer, or note the deferral in the design doc.

Resolution

Unresolved.