fix(security): running drivers refuse out-of-namespace credential refs at resolve time (#834)
v2-ci / unit-tests (push) Has been cancelled
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:
+32
-34
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user