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
+32 -34
View File
@@ -1453,18 +1453,20 @@ Enforced, fail-closed, at every seam — the earlier ones exist for a clear mess
4. **Live browse** — `BrowserSessionService.OpenAsync` refuses before any bespoke or universal browser opens.
5. **Resolve time** — `GalaxySecretRef`, `GalaxyAckCredentialResolver`, `OpcUaUserIdentityFactory` and
`HeidenhainCredentials` all resolve through `CredentialReferences`, which re-checks the scope **before** any
secret-store or environment read. This is hard-fail on every admin-node path (the Galaxy and OpcUaClient
AdminUI browsers, every Test Connect probe) and everywhere for Heidenhain. The one exception is the deprecated
warn-only compatibility path for already-deployed drivers, below.
secret-store or environment read. This is hard-fail on **every** path — the running drivers (Galaxy
`InitializeAsync` / every gateway `ReopenAsync` / the ack fallback, OpcUaClient session open), the AdminUI
browsers and every Test Connect probe. The #815 warn-only window for already-deployed drivers is **over**
(lmxopcua#834, below).
Messages name the field and the allowed forms, never the value. Out of scope by design: `${secret:}` tokens in
`appsettings.json` (host config, not operator-authored), and the `Sql` driver's `connectionStringRef`, which is
already a fixed prefix (`Sql__ConnectionStrings__<ref>`) whose value carries its own server — a Designer can
choose *which* provisioned database a ref names, but cannot redirect its credentials to another host.
**Migration (existing configs).** A stored config with an out-of-namespace reference is listed by the upgrade
preflight (below), refused by its next deploy (`CredentialReferenceOutOfScope` — the message names the
migration), and refused by Test Connect / live browse. Values most likely to be in real config databases, with
**Migration (existing configs).** A stored config with an out-of-namespace reference is listed by the
credential-reference preflight (below), refused by its next deploy (`CredentialReferenceOutOfScope` — the message
names the migration), refused by Test Connect / live browse, and — since lmxopcua#834 — refused by a **running**
driver at resolve time: it does not connect until the field is migrated and redeployed. Values most likely to be in real config databases, with
the exact replacement (create the new secret / variable first — on every node that runs the driver **and** on
the admin nodes, which run Test Connect and browse — then edit the field):
@@ -1480,30 +1482,27 @@ the admin nodes, which run Test Connect and browse — then edit the field):
| OpcUaClient `SECRET:x` / `Secret:x` — pre-#815 resolved case-insensitively | prefixes are now exact | `secret:opcuaclient/<name>` |
| OpcUaClient **literal** password that happens to start with `env:`, `file:`, `secret:`/`${secret:` in any casing (e.g. a real password `Env:Prod1`) — pre-#815 sent it verbatim | it now parses as a reference | store it: `secret:opcuaclient/<name>` (a literal that does not start with one of those prefixes is unaffected) |
**Warn-only compatibility for already-deployed drivers (⚠️ deprecated — a later release fails closed).** Refusing
at resolve time would fault running plant drivers at the upgrade restart — and, for Galaxy, at **every gateway
reconnect**: `GalaxyDriver.ReopenAsync` (the `ReconnectSupervisor` callback) rebuilds the client options through
`BuildClientOptionsAsync`, which re-resolves `Gateway.ApiKeySecretRef` each time, so a running driver would fault
at its next reconnect, not at a deploy. So, for one compatibility window, the running-driver call sites — Galaxy
`InitializeAsync` / `ReopenAsync` / the ack-fallback resolver, and OpcUaClient session open — resolve an
out-of-namespace reference with the **old** semantics (Galaxy: case-insensitive `env:`/`file:`/`dev:`/`secret:`,
literal otherwise; OpcUaClient: case-insensitive `secret:`, literal otherwise) and log a Warning naming the
driver, field and allowed form (never the value), at most once per field per hour. The use also rides the
driver's diagnostics bag (`credential-compat:<field>`) to `/hosts` and to the `/raw` credential banner. This is
chosen **by call site**, not by a flag (`LegacyCredentialReferenceTracker`): the AdminUI browsers and every probe
never get the tracker and stay hard-fail, and Heidenhain (new driver, no legacy configs) is hard-fail everywhere.
It cannot be used to exfiltrate: save, Test Connect, browse and the deploy gate all refuse such a reference, so it
can only be the reference an administrator deployed **before** the upgrade, and it lives only until that driver's
next successful deploy (which requires migrating it). The hard-fail release deletes the tracker, the per-driver
`Legacy…` resolve methods and their `legacy` parameters — nothing else changes.
**The compatibility window is over (lmxopcua#834, 2026-11-13).** The first #815 release let an already-deployed
Galaxy / OpcUaClient driver keep resolving a pre-#815 out-of-namespace reference with the old semantics, with a
rate-limited Warning and a `credential-compat:<field>` diagnostics entry (`LegacyCredentialReferenceTracker`). That
path is deleted: every value in the table above — `env:MX_API_KEY` (the old Galaxy form default), any other
out-of-namespace `env:` / `secret:`, every `file:` and every non-lower-case prefix — now fails at resolve time with
the same `CredentialReferenceException` the save path, the deploy gate, Test Connect and browse raise, before any
store, environment or file read. For Galaxy that includes **every gateway reconnect** (`ReopenAsync` rebuilds the
client options through `BuildClientOptionsAsync`) and the ack fallback password (the acknowledge is refused); for
OpcUaClient it is the session open, before any endpoint is dialled. Removal was gated on the DEV and QA ConfigDbs
holding no Galaxy / OpcUaClient driver (checked 2026-11-13); no production install exists, so any future one gets the
strict behaviour from its first deploy. An upgrade from a pre-#815 build with such a config must migrate it **before**
the upgrade — the preflight below lists it.
**Upgrade preflight.** On an admin node, `CredentialReferencePreflightService` runs once, 15 s after
`ApplicationStarted` (never inside an Akka starter, and it resolves nothing — ConfigDb reads only). It scans
every credential-resolving driver's stored `DriverConfig` / `DeviceConfig` rows (**Draft**) and the latest
deployment artifact (**Deployed** — what the running drivers were given) and logs one Warning per finding:
driver, device, field, allowed form, never the value. The same list, plus running drivers that reported a
warn-only resolution (**Running**, from driver-health diagnostics, fleet-wide), is shown as a banner on `/raw`,
with a Re-check button.
**Credential-reference preflight (a hard error).** On an admin node, `CredentialReferencePreflightService` runs
once, 15 s after `ApplicationStarted` (never inside an Akka starter, and it resolves nothing — ConfigDb reads only).
It scans every credential-resolving driver's stored `DriverConfig` / `DeviceConfig` rows (**Draft** — a deploy the
gate will refuse) and the latest sealed deployment artifact (**Deployed** — a driver that refuses its credential and
does not connect) and logs one **Error** per finding: driver, device, field, allowed form, never the value. The same
list is shown as a red banner on `/raw`, with a Re-check button. It stays because it is the one place that names a
broken config *before* someone deploys it or wonders why a driver is down — e.g. after restoring an old ConfigDb
backup or importing a pre-#815 config — and it also carries the #835 cross-instance and #836/#850 path checks.
#### Per-instance credential references (#835, #848, #849)
@@ -1660,11 +1659,10 @@ service account can read (another product's client certificate, a host certifica
- **The admin nodes and the driver nodes must hold the same relative layout** (the browse loads the certificate on the
admin node).
- `UserCertificatePassword` stays covered by #815 (`secret:opcuaclient/…` / `env:OTOPCUA_OPCUACLIENT_…` / literal).
- **Already-running drivers (deprecated warn-only window):** a deployed driver whose path is a pre-#836 **absolute** path
keeps loading it, with a rate-limited Warning (driver + field, never the path) and a
`credential-compat:UserCertificatePath` diagnostics entry, until its next deploy (which the gate refuses). The AdminUI
browse never gets the tracker (hard-fail). Migration: move the PFX under the directory on every node that runs the
driver **and** the admin nodes, then set the field to its relative path.
- **Already-running drivers:** the #836 warn-only window ended with lmxopcua#834 — a deployed driver whose path is a
pre-#836 **absolute** path now refuses it at session open (`CredentialReferenceException`), exactly like the browse and
the deploy gate. Migration: move the PFX under the directory on every node that runs the driver **and** the admin
nodes, then set the field to its relative path and redeploy.
### Role grant source