fix(security): running drivers refuse out-of-namespace credential refs at resolve time (#834)
v2-ci / unit-tests (push) Has been cancelled

The #815 warn-only compatibility window is over. A running Galaxy driver
(InitializeAsync, every gateway ReopenAsync, the ack fallback password) and a
running OpcUaClient driver (session open) now refuse an out-of-namespace
credential reference with the same CredentialReferenceException that save,
deploy (CredentialReferenceOutOfScope), Test Connect and browse already raise,
before any store / environment / file read and before any endpoint is dialled.
The one existing scope check (CredentialReferences.Parse/ResolveAsync) is now
the only path; nothing new was added.

Removed:
- LegacyCredentialReferenceTracker (Core.Abstractions), its rate-limited WARN
  and the credential-compat:<field> diagnostics entry.
- The per-driver Legacy* resolve methods and every `legacy` parameter
  (GalaxySecretRef, GalaxyAckCredentialResolver, OpcUaUserIdentityFactory,
  OpcUaUserCertificatePaths, OpcUaClientSecretResolution).
- IDriverDiagnostics on GalaxyDriver / OpcUaClientDriver (it only carried the
  tracker's entries).
- The tracker also kept a pre-#836 absolute UserCertificatePath loading on a
  running OpcUaClient driver; that is refused now too.

Preflight / banner decision: KEPT, as a hard error. The Running source
(driver-health credential-compat entries) and CredentialReferenceBannerModel
are gone with the tracker, but the ConfigDb scan still tells an operator
something no other surface does: a Deployed finding is now a driver that is
not connecting, a Draft finding is a deploy the gate will refuse - named
before anyone deploys, e.g. after restoring an old ConfigDb backup or
importing a pre-#815 config. It also carries the #835 cross-instance and
#836/#850 path checks. CredentialReferencePreflightService now logs one Error
per finding (was Warning) with no warn-only wording, and the /raw banner is
alert-danger.

DEV and QA ConfigDbs hold no Galaxy/OpcUaClient driver (checked 2026-11-13);
no production install exists.

Tests: GalaxyDriverLegacyCredentialTests replaced by
GalaxyDriverCredentialScopeTests; new OpcUaClientDriverCredentialScopeTests;
tracker tests in OpcUaClientSecretResolutionTests /
OpcUaClientUserCertificatePathTests deleted; AdminUI preflight tests drop the
Running/banner-model cases and assert Error level. Against the old code the
new refusal tests fail (Galaxy 5/6, OpcUaClient 4/5; the two positive controls
pass on both).

docs/security.md: the migration table now says running drivers refuse; the
warn-only section is replaced by "The compatibility window is over".

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 02:04:18 -05:00
parent 2cb8a2c317
commit f0c6cf9640
19 changed files with 433 additions and 732 deletions
@@ -1,41 +1,38 @@
@using Microsoft.EntityFrameworkCore
@using ZB.MOM.WW.OtOpcUa.AdminUI.Deployments
@using ZB.MOM.WW.OtOpcUa.AdminUI.Hubs
@using ZB.MOM.WW.OtOpcUa.Configuration
@inject CredentialReferencePreflightState State
@inject IDriverStatusSnapshotStore DriverStatus
@inject IServiceProvider Services
@* lmxopcua#815 upgrade preflight surface: stored / deployed configs whose credential references sit outside their
driver's namespace (the boot scan, re-runnable here) plus running drivers that reported resolving one through the
deprecated warn-only compatibility path (driver-health diagnostics, fleet-wide). Never shows a value.
The two sources are independent (lmxopcua#847): a failed ConfigDb scan shows a note, and the running findings
— read from the in-process health store — still render. See CredentialReferenceBannerModel. *@
@* lmxopcua#815 credential-reference preflight surface — a hard error since #834: stored / deployed configs whose
credential references sit outside their driver's namespace (the boot scan, re-runnable here). The warn-only
compatibility path for running drivers is gone, so a Deployed finding is a driver that refuses the reference at
resolve time and does not connect; a Draft finding is a deploy the gate will refuse. Never shows a value.
A failed re-check keeps the last successful scan's findings and says so. *@
@if (_model.Visible)
@if (_snapshot.Findings.Count > 0 || _snapshot.Error is not null)
{
<div class="alert alert-warning small mb-3" role="alert">
<div class="alert alert-danger small mb-3" role="alert">
<div class="d-flex justify-content-between align-items-start gap-2">
<div>
<strong>Credential references outside their driver's namespace (lmxopcua#815).</strong>
The deploy gate refuses these; a driver deployed before the upgrade keeps resolving them in
deprecated warn-only mode until its next deploy. Migrate each to the allowed form — see
docs/security.md "Credential references are namespaced per driver".
The deploy gate refuses these, and a deployed driver refuses them when it resolves its credentials, so it
does not connect. Migrate each to the allowed form and redeploy — see docs/security.md
"Credential references are namespaced per driver".
</div>
<button class="btn btn-sm btn-outline-secondary" disabled="@_busy" @onclick="RecheckAsync">Re-check</button>
</div>
@if (_model.ScanError is not null)
@if (_snapshot.Error is not null)
{
<div class="text-danger mt-1" data-testid="credential-scan-error">
@_model.ScanError Stored and deployed configs were not checked
@(_model.ScanFindings.Count > 0 ? "(the list below is from the last successful scan)" : "")
— running-driver findings below are still live.
<div class="mt-1" data-testid="credential-scan-error">
@_snapshot.Error Stored and deployed configs were not checked
@(_snapshot.Findings.Count > 0 ? "(the list below is from the last successful scan)" : "").
</div>
}
@if (_model.ScanFindings.Count > 0)
@if (_snapshot.Findings.Count > 0)
{
<ul class="mb-0 mt-2">
@foreach (var f in _model.ScanFindings.Take(MaxRows))
@foreach (var f in _snapshot.Findings.Take(MaxRows))
{
<li>
<span class="badge bg-secondary me-1">@f.Source</span>
@@ -46,26 +43,9 @@
</li>
}
</ul>
@if (_model.ScanFindings.Count > MaxRows)
@if (_snapshot.Findings.Count > MaxRows)
{
<div class="mt-1 text-muted">…and @(_model.ScanFindings.Count - MaxRows) more (see the node log).</div>
}
}
@if (_model.RunningFindings.Count > 0)
{
<ul class="mb-0 mt-2" data-testid="credential-running-findings">
@foreach (var f in _model.RunningFindings.Take(MaxRows))
{
<li>
<span class="badge bg-secondary me-1">@f.Source</span>
driver <span class="mono">@f.DriverName</span>
— @f.Problem
</li>
}
</ul>
@if (_model.RunningFindings.Count > MaxRows)
{
<div class="mt-1 text-muted">…and @(_model.RunningFindings.Count - MaxRows) more running.</div>
<div class="mt-1 text-muted">…and @(_snapshot.Findings.Count - MaxRows) more (see the node log).</div>
}
}
</div>
@@ -73,13 +53,10 @@
@code {
private const int MaxRows = 25;
private CredentialReferenceBannerModel _model = new([], [], null, null);
private CredentialReferencePreflightState.Snapshot _snapshot = new([], null, null);
private bool _busy;
protected override void OnInitialized() => Compose(State.Current);
private void Compose(CredentialReferencePreflightState.Snapshot snapshot)
=> _model = CredentialReferenceBannerModel.Compose(snapshot, DriverStatus.GetAll());
protected override void OnInitialized() => _snapshot = State.Current;
private async Task RecheckAsync()
{
@@ -87,29 +64,23 @@
try
{
var factory = Services.GetService(typeof(IDbContextFactory<OtOpcUaConfigDbContext>)) as IDbContextFactory<OtOpcUaConfigDbContext>;
CredentialReferencePreflightState.Snapshot snapshot;
if (factory is null)
{
snapshot = State.Current with { Error = "No config DB on this node." };
}
else
{
try
{
var findings = await new CredentialReferencePreflight(factory).ScanAsync(CancellationToken.None);
snapshot = new CredentialReferencePreflightState.Snapshot(findings, DateTime.UtcNow, null);
State.Set(snapshot);
}
catch (Exception)
{
// Keep the last successful scan's findings (flagged as such by the note) — and, above all,
// recompose the RUNNING findings from the live health store rather than leaving whatever the
// last render had (lmxopcua#847).
snapshot = State.Current with { Error = "The credential-reference preflight could not read the config DB." };
}
_snapshot = State.Current with { Error = "No config DB on this node." };
return;
}
Compose(snapshot);
try
{
var findings = await new CredentialReferencePreflight(factory).ScanAsync(CancellationToken.None);
_snapshot = new CredentialReferencePreflightState.Snapshot(findings, DateTime.UtcNow, null);
State.Set(_snapshot);
}
catch (Exception)
{
// Keep the last successful scan's findings, flagged as such by the note.
_snapshot = State.Current with { Error = "The credential-reference preflight could not read the config DB." };
}
}
finally
{
@@ -17,17 +17,18 @@ public enum CredentialFindingSource
/// <summary>A stored DriverConfig / DeviceConfig row (what the next deploy will gate).</summary>
Draft,
/// <summary>The latest deployment artifact (what the running drivers were given).</summary>
/// <summary>
/// The latest sealed deployment artifact (what the running drivers were given). Since lmxopcua#834 a driver
/// refuses such a reference at resolve time, so this driver is already failing, or fails on its next
/// initialise / reconnect.
/// </summary>
Deployed,
/// <summary>A running driver that reported resolving it through the #815 warn-only compatibility path.</summary>
Running,
}
/// <summary>One out-of-namespace credential reference (never carries the value).</summary>
/// <param name="Source">Where it was found.</param>
/// <param name="DriverType">The driver type.</param>
/// <param name="DriverName">The driver's display name (or instance id for a running driver).</param>
/// <param name="DriverName">The driver's display name.</param>
/// <param name="DriverInstanceId">The driver instance id.</param>
/// <param name="DeviceName">The device, when the reference sits in a DeviceConfig.</param>
/// <param name="Problem">The field and the allowed forms.</param>
@@ -35,10 +36,13 @@ public sealed record CredentialReferenceFinding(
CredentialFindingSource Source, string DriverType, string DriverName, string DriverInstanceId, string? DeviceName, string Problem);
/// <summary>
/// Upgrade preflight for lmxopcua#815: lists every stored or deployed DriverConfig / DeviceConfig whose credential
/// fields carry a reference outside the driver's namespace — configs written before the namespaces existed that
/// the deploy gate will now refuse (and that a running driver resolves only in warn-only compatibility mode).
/// Reads the ConfigDb only; resolves nothing, so it never touches the secret store or the environment.
/// Credential-reference preflight (lmxopcua#815, a hard error since #834): lists every stored or deployed
/// DriverConfig / DeviceConfig whose credential fields carry a reference outside the driver's namespace (or a
/// refused key-material path, #836/#850, or a cross-instance reference, #835) — configs written before the
/// namespaces existed, restored from a backup, or imported. A Draft finding is a deploy the gate will refuse; a
/// Deployed finding is a driver that refuses the reference at resolve time (it does not start, or stops on its
/// next reconnect). Reads the ConfigDb only; resolves nothing, so it never touches the secret store or the
/// environment.
/// </summary>
/// <param name="dbFactory">The config DB.</param>
public sealed class CredentialReferencePreflight(IDbContextFactory<OtOpcUaConfigDbContext> dbFactory)
@@ -118,60 +122,6 @@ public sealed class CredentialReferencePreflight(IDbContextFactory<OtOpcUaConfig
return findings;
}
/// <summary>
/// Running drivers that reported a warn-only legacy resolution on their diagnostics bag
/// (<see cref="LegacyCredentialReferenceTracker.DiagnosticsKeyPrefix"/>), fleet-wide via the driver-health feed.
/// </summary>
/// <param name="snapshots">The driver-health snapshots.</param>
/// <returns>The findings.</returns>
public static IReadOnlyList<CredentialReferenceFinding> RunningFindings(IEnumerable<Commons.Messages.Drivers.DriverHealthChanged> snapshots) =>
snapshots
.Where(s => s.Diagnostics is not null)
.SelectMany(s => s.Diagnostics!
.Where(kv => kv.Key.StartsWith(LegacyCredentialReferenceTracker.DiagnosticsKeyPrefix, StringComparison.Ordinal))
.Select(kv => new CredentialReferenceFinding(
CredentialFindingSource.Running, "", s.DriverInstanceId, s.DriverInstanceId, null,
$"{kv.Key[LegacyCredentialReferenceTracker.DiagnosticsKeyPrefix.Length..]}: {kv.Value}")))
// Both nodes of a redundant pair run the same driver and report the same finding; the health store
// keeps one snapshot per (driver, node) since lmxopcua#847, so collapse the identical pair here.
.Distinct()
.ToList();
}
/// <summary>
/// What the <c>/raw</c> credential banner renders (lmxopcua#847), composed from two INDEPENDENT sources: the
/// ConfigDb scan (draft + deployed rows) and the live driver-health feed (running drivers' warn-only
/// <c>credential-compat:*</c> resolutions). A failed ConfigDb scan must never hide the running findings — they
/// come from the in-process health store and are exactly what is still true while the database is unreachable.
/// </summary>
/// <param name="ScanFindings">Draft / Deployed findings from the last successful scan (empty when it failed).</param>
/// <param name="RunningFindings">Running-driver findings from the live health feed.</param>
/// <param name="ScanError">The scan failure note, or null when the scan succeeded (or has not run).</param>
/// <param name="ScannedAtUtc">When the scan last ran.</param>
public sealed record CredentialReferenceBannerModel(
IReadOnlyList<CredentialReferenceFinding> ScanFindings,
IReadOnlyList<CredentialReferenceFinding> RunningFindings,
string? ScanError,
DateTime? ScannedAtUtc)
{
/// <summary>Whether the banner renders at all.</summary>
public bool Visible => ScanFindings.Count > 0 || RunningFindings.Count > 0 || ScanError is not null;
/// <summary>Composes the banner from the last scan result and the current driver-health snapshots.</summary>
/// <param name="scan">The last preflight result.</param>
/// <param name="healthSnapshots">The live driver-health snapshots.</param>
/// <returns>The banner model.</returns>
public static CredentialReferenceBannerModel Compose(
CredentialReferencePreflightState.Snapshot scan,
IEnumerable<Commons.Messages.Drivers.DriverHealthChanged> healthSnapshots)
{
ArgumentNullException.ThrowIfNull(scan);
var running = CredentialReferencePreflight.RunningFindings(healthSnapshots ?? []);
// Running-source rows only ever come from the health feed; a scan result never carries them.
var scanned = scan.Findings.Where(f => f.Source != CredentialFindingSource.Running).ToList();
return new(scanned, running, scan.Error, scan.ScannedAtUtc);
}
}
/// <summary>The last preflight result, shown by the AdminUI <c>/raw</c> credential banner.</summary>
@@ -194,7 +144,7 @@ public sealed class CredentialReferencePreflightState
}
/// <summary>
/// Runs <see cref="CredentialReferencePreflight"/> once after host start on an admin node and logs one Warning per
/// Runs <see cref="CredentialReferencePreflight"/> once after host start on an admin node and logs one Error per
/// finding (driver, device, field, allowed forms — never a value). Scheduled after <c>ApplicationStarted</c> plus a
/// short delay, off every Akka starter; it needs only the ConfigDb, never <c>ISecretResolver</c>.
/// </summary>
@@ -250,20 +200,20 @@ public sealed class CredentialReferencePreflightService(
state.Set(new(findings, DateTime.UtcNow, null));
foreach (var f in findings)
{
logger.LogWarning(
"Credential-reference preflight (lmxopcua#815): {Source} {DriverType} driver '{DriverName}'{Device}: {Problem} "
+ "The deploy gate refuses this; a running driver resolves it only in deprecated warn-only mode. "
+ "See docs/security.md \"Credential references are namespaced per driver\".",
logger.LogError(
"Credential-reference preflight (lmxopcua#815/#834): {Source} {DriverType} driver '{DriverName}'{Device}: {Problem} "
+ "The deploy gate refuses this, and a running driver refuses it at resolve time (the driver does not "
+ "connect). See docs/security.md \"Credential references are namespaced per driver\".",
f.Source, f.DriverType, f.DriverName, f.DeviceName is null ? "" : $" device '{f.DeviceName}'", f.Problem);
}
if (findings.Count == 0)
logger.LogInformation("Credential-reference preflight (lmxopcua#815): every stored and deployed reference is namespaced.");
logger.LogInformation("Credential-reference preflight (lmxopcua#815/#834): every stored and deployed reference is namespaced.");
return findings;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
logger.LogWarning(ex, "Credential-reference preflight (lmxopcua#815) could not read the config DB.");
logger.LogWarning(ex, "Credential-reference preflight (lmxopcua#815/#834) could not read the config DB.");
state.Set(new([], DateTime.UtcNow, "The credential-reference preflight could not read the config DB."));
return [];
}