lmxopcua/docs/plans/2026-07-31-apikey-acl-enforcement-design.md

API-key identity + node ACL enforcement (Gitea #520)

Status: design agreed 2026-07-31, not yet implemented. Supersedes: docs/v2/acl-design.md (LDAP-group-keyed model, never wired).

Why this exists

IPermissionEvaluator + TriePermissionEvaluator + PermissionTrieCache + PermissionTrieBuilder have lived in src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/ with 30 passing unit tests and zero production call sites since v2. Operators can author NodeAcl rows at /clusters/{id}/acls; ConfigComposer snapshots every row into every deployment artifact, so an ACL edit shifts the artifact RevisionHash and ships fleet-wide — and DeploymentArtifact never deserializes them. The bytes arrive and are dropped.

Actual enforcement today is two server-wide role checks: WriteOperate on Value writes (either realm) and AlarmAck on the five Part 9 alarm methods. Read, Browse, HistoryRead and CreateMonitoredItems have no authorization check at all, so any admitted session — including Anonymous — reads the entire address space.

Re-verified on master 2026-07-31 (all six claims still true). Both AdminUI warning banners and the corrected docs from 2026-07-27 are in place, so the trap is signposted but still a trap.

Decisions taken (owner, 2026-07-31)

#	Decision	Consequence
D1	The OPC UA data plane is machine-to-machine. Identity is an API key presented with a static username, not an LDAP user.	NodeAcl keys on a principal, not an LDAP group — blocker #2 dissolves rather than being solved.
D2	Replace LDAP entirely on the OPC UA data plane.	LdapOpcUaUserAuthenticator and the OPC UA half of Security:Ldap are deleted. AdminUI login keeps its own LDAP — untouched.
D3	Anonymous is a normal, grantable principal, gated by a new enable setting.	When enabled, Anonymous resolves to the reserved principal anonymous and can be granted read or write like any key. When disabled, anonymous session activation is rejected.

D3 is the neat one: it removes Anonymous as a special case in the evaluator. There is no "anonymous bypass" branch to get wrong — an ungranted anonymous session is denied by the same fail-closed path as an ungranted key.

Assumption I am making explicit (not asked)

Enforcement ships behind Security:Acl:Enabled, default false. This is the dark-switch discipline MeshTransport / ConfigSource / Telemetry all shipped under: both sides are wired in both modes, the flip is a config change rather than a redeploy. Without it, the first deploy carrying this code would silently start denying every client that has no key — including ScadaBridge's Data Connection Layer, which consumes this address space from another repo. The authenticator swap (D2) is not dark-switchable in the same way and is a hard cutover; that asymmetry is deliberate and called out in the rollout stage.

Identity model

OPC UA UserName token            Anonymous token
  username = <static>              (no credential)
  password = <api key secret>
        |                               |
        v                               v
  ApiKeyOpcUaUserAuthenticator    Security:Acl:AllowAnonymous ?
        |                               |
        v                               v
     principal set  <-------------  "anonymous"
        |
        v
  PermissionTrie (per cluster, per artifact revision)

• Key format mirrors the family convention (histgw_<id>_<secret> in HistorianGateway, apikey create-key in mxaccessgw): otua_<keyId>_<secret>. The keyId prefix makes lookup an index hit rather than a scan over every stored hash.
• Storage is a hash, never the secret — HMAC-SHA256 under a server pepper, compared with CryptographicOperations.FixedTimeEquals. The plaintext is shown once at creation in AdminUI and is unrecoverable afterwards.
• A key maps to one or more named principals, and NodeAcl rows key on the principal name. The indirection is deliberate: many keys (one per consuming system, independently revocable) share one grant set, and rotating a key never touches an ACL row.

NodeAcl.LdapGroup → NodeAcl.Principal

A rename + migration, not a new column. The trie walker is unchanged — it already matches an opaque string; only what produces that string changes.

The four blockers, re-scoped

#	#520's blocker	Resolution under this design
1	Raw-realm nodes have no representable NodeScope (NodeHierarchyKind has one member, Equipment)	Add NodeHierarchyKind.Raw. ⚠️ This cell was wrong about the shape — it described the path as the five-tuple Folder/Driver/Device/TagGroup/Tag, but folders and tag groups both self-nest, so the real path is folder… / Driver / Device / group… / Tag with unbounded depth on two axes. The fix was therefore not an enum member but a variable-depth NodeScope + segment-loop walk. FolderSegment was not repurposed as the raw-folder level; it is retired, and RawFolder/RawDriver/RawDevice/RawTagGroup were appended instead. Correctly identified as the one genuine design item.
2	Session carries roles, not LDAP groups	Dissolved by D1 — the principal comes from the key, not from a directory.
3	PermissionTrieBuilder's scopePaths has no producer	Done in stage 3 — AclScopePathResolver, built node-side from the artifact's raw + UNS topology (no DB read, so a driver-only node can build it). The coverage note was right in substance but imprecise: six tests did pass a scopePaths dictionary, but every one hand-wrote it in the test body with exactly the segments the walker expected, so nothing pinned a producer — and there was none to pin. That gap is closed by an artifact → parse → build → walk test.
4	No session lifecycle / AuthGenerationId	Stamp the generation from the artifact RevisionHash at session activation; a new deploy invalidates cached decisions. UserAuthorizationState already has the freshness predicates.

Plus, from the same audit: the node never parses ACLs out of the artifact, and OtOpcUaNodeManager has no cluster identity (NodeScope.ClusterId is required and the evaluator fails closed on mismatch).

Enforcement seams

Operation	Seam today	Work
Write (Value)	EvaluateEquipmentWriteGate — pure, fail-closed, unit-testable	Swap the role check for an ACL decision. Runs under the node-manager Lock, so the check must stay non-blocking — the evaluator is pure, which fits.
Alarm ack/confirm/shelve	two AlarmAck role gates	Same swap.
HistoryRead	HistoryReadRawModified / Processed / AtTime / Events overrides already exist	Add the check inside them.
Read / Browse / Subscribe	none	The real gap. Needs a Read override or per-variable OnSimpleReadValue, on the hot publish path — so the decision must be cached per (session, node), not evaluated per value.

Smaller inconsistencies to settle en route

• NodeAclScopeKind.FolderSegment is offered in the authoring dropdown but the trie walker has no level to match it at — settled in stage 3, but not the way this line assumed. It is a retired v2 concept (it described the SystemPlatform/Galaxy hierarchy v3 deleted), so rather than being given a level it is now explicitly unresolvable, with RawFolder as its v3 replacement. It survives in the enum only because the artifact stores the ordinal, so removing it would renumber every later member in every deployed artifact. The dropdown labels it retired, and the deploy gate names it. ⚠️ The old claim that the walker could not match it was slightly overstated: Build routed it through Descend like any other kind, so given a path it would have matched and been reported under whatever level it happened to land on. It was unlabellable, not unplaceable.
• NodePermissions.AlarmRead has no OpcUaOperation mapping — grantable but unreachable.
• NodeAcl.ScopeId has no FK and no existence check, so scope ids dangle silently.
• ZB.MOM.WW.OtOpcUa.OpcUaServer.csproj does not reference Core at all — stale; stage 1 added the reference. The line read as an open item long after it was closed.
• NodePermissions.HistoryUpdate is deliberately in no bundle until HistoryUpdate exists. Leave it.

Stages

Each stage is one commit, builds clean, and leaves the tree shippable.

1. ✅ Foundation — principal model. NodeAcl.LdapGroup → Principal (+ migration); ApiKey entity

   • store + hashing; OpcUaServer.csproj references Core. No behaviour change.

2. ✅ Identity cutover. ApiKeyOpcUaUserAuthenticator replaces LdapOpcUaUserAuthenticator on the OPC UA data plane; Anonymous resolves to the anonymous principal or is rejected per setting. AdminUI LDAP untouched.

3. Raw scope. ✅ Done. NodeHierarchyKind.Raw, a variable-depth scope model, the scopePaths producer (AclScopePathResolver) fed from the artifact, a deploy-time gate for ACL scopes, and the first coverage of the production hierarchy path.

   It was substantially larger than this line originally implied, because the sketch had the shape of the raw tree wrong. The plan said the Raw path is the five-tuple Folder/Driver/Device/TagGroup/Tag. It is not: RawFolder.ParentRawFolderId and TagGroup.ParentTagGroupId are both self-referencing, so folders and tag groups each nest without bound and a real RawPath is folder… / Driver / Device / group… / Tag. NodeScope was fixed-arity (five nullable level fields) and PermissionTrie.CollectMatches was five hardcoded steps, so the scope model could not address a real raw tree at all. NodeScope is now {ClusterId, Kind, IReadOnlyList<string> Segments} and the walk is a segment loop. Good news found en route: the trie structure was already variable-depth (NodeAclPath.Segments is a list; PermissionTrieNode.Children is a recursive dictionary), so only the walker and the scope record had to change.

   Four decisions worth keeping:

   • The namespace level became the realm. Level 1 of the walk gated on NodeScope.NamespaceId, but v3 has no Namespace entity — the snapshot was retired when the address space went dual-namespace, and the identifier appeared nowhere in production outside NodeScope. So level 1 could only ever fail to match, which silently made every sub-cluster grant unreachable while cluster grants kept working. It is now the realm token (raw/uns), derived from the scope's Kind by NodeAclRealms rather than carried on it, so the walk and the path producer cannot disagree about its spelling. NodeAclScopeKind.Namespace becomes meaningful again as "a whole realm".
   • Provenance comes from the granting row's ScopeKind, recorded on TrieGrant at build time, not from the depth the grant sits at. Depth-derived provenance could not name a raw level at all (the depth of "Device" varies with folder nesting) and misreported any path whose length disagreed with its kind.
   • The trie comparer moved from OrdinalIgnoreCase to Ordinal. Raw sibling-name uniqueness is ordinal, so Speed and speed can both exist under one device and a grant on either would have matched both — a silent widening. Case-sensitive is also the fail-closed direction.
   • The null-scopePaths "deterministic test mode" is deleted. It planted unresolvable rows at a direct child of the trie root, a position the walker cannot reach — so the grant looked placed and could never match, and every test using that mode proved nothing about production placement. An unresolvable row is now dropped with a diagnostic, and scopePaths is required.

   A scope resolves to a list of paths, not one: a raw tag projected into N equipments is reachable at N+1 NodeIds and a write through any of them lands on the same driver reference, so a Tag-scoped grant that covered only the raw node would be bypassable through a UNS one. The lookup is keyed on (ScopeKind, ScopeId) rather than ScopeId alone, because ScopeId has no FK and no type discriminator — ids are prefixed only by convention, and an id collision across entity types would hand a grant the wrong node's paths.

   Also closed here: NodeAcl rows had no deploy-time validation of any kind and were not even reachable from DraftValidator (DraftSnapshot carried no NodeAcls collection). They are now gated for dangling ids, cross-cluster scopes, blank/contradictory ScopeId, the retired FolderSegment kind, and undefined ordinals. That gate is what substitutes for the ACL scope picker until stage 7 — ScopeId is still a free-text box.

4. Artifact + lifecycle. ✅ Done. ConfigComposer snapshots ApiKeys alongside the NodeAcls it already carried; DeploymentArtifact.ParseDataPlaneAuthority decodes both node-side (grants scoped to the node's own cluster, keys not — a key is a fleet-wide credential and the ACL rows are what bind it); OpcUaPublishActor installs them on DataPlaneAuthorityState on every apply; ArtifactApiKeyStore serves them to session activation on a driver-only node, which until now denied every UserName token; and OtOpcUaNodeManager gains a DataPlaneAuthority property, which is the cluster identity blocker #4 named.

   Two things went differently from the sketch, both deliberately:

   • The generation is a counter, not the hash. "Stamp the generation from the RevisionHash" reads as "derive a long from the hash bytes", and that is wrong: PermissionTrieCache treats the highest GenerationId as current (ClusterEntry.WithAdditional) and Prune keeps the highest, while hash fragments are unordered — so roughly half of all deploys would install a lower generation and the cache would keep serving the previous deployment's ACLs, silently. The hash still drives the stamp (a new hash advances it, a re-applied one does not); it just does not become it.
   • Sessions are not stamped yet. Building a UserAuthorizationState per session belongs with the first seam that reads one, in stage 5. Constructing one now would be a per-session object nothing consults — the dormant-wiring failure mode this repo has been bitten by before.

   Also settled here: the feed runs before OpcUaPublishActor's plan.IsEmpty early-return. An artifact that only revokes a key produces an empty address-space plan, so feeding after that return would leave the revoked key working until some unrelated structural change happened to redeploy.

5. Enforce write + alarms + HistoryRead. ✅ Done. AclOptions (Security:Acl:Enabled, default false); DataPlaneAuthorizer projects a NodeId + realm onto a NodeScope and evaluates it through the existing TriePermissionEvaluator; the trie is built and installed inside DataPlaneAuthorityState.Apply; both IApiKeyStore implementations widened to the full grant set.

   Five things went differently from this line, all deliberate:

   • The role check is REPLACED, not supplemented. Running both in series would require a grant to confer the server-wide role as well as pass the scope check — and only Cluster-scoped grants confer a role — so every narrow grant would have stayed inert and the flag would have looked inert too. Narrow grants working is the point of the stage. Pinned by a test that writes successfully from a session carrying no roles at all; the deny-side test alone passes against a build where the ACL is never consulted, because the role gate denies too.
   • UserAuthorizationState is built per CALL, not per session. The per-session shape was LDAP-inherited: it exists so a long-lived session can re-resolve group membership that changed out of band. Nothing can change out of band under API keys, so the generation stamp is the whole invalidation signal and a per-call record picks it up for free — where a cached one would need explicit invalidation to do the same job. IsStale/NeedsRefresh therefore cannot fire here and are documented as vestigial rather than left looking load-bearing. Stage 6 is where caching earns its keep, and it wants a per-(session, node) decision cache, not this type.
   • Revocation now reaches an OPEN session, which the sketch did not ask for. Every decision re-checks the authenticating key against the current snapshot. Without it a key revoked by a deployment kept its open session's authority until the client chose to reconnect — indefinitely, for a machine-to-machine consumer — which would have made the documented "revocation requires a deploy" sharp edge considerably sharper than documented.
   • The trie is built inside DataPlaneAuthorityState.Apply, not by a separate install step at the publish actor. As two wirings, the trie install is the one that silently does not run, and an absent trie denies everything — indistinguishable from working enforcement until someone checks that an ALLOW is possible. Falsified: deleting the install turns 13 of the 22 stage-5 tests red.
   • The deploy log now reports what the BUILD dropped instead of re-deriving it. The previous unresolvedScopes count agreed with the builder on one of its four drop reasons; a rule with a blank ScopeId, a retired scope kind, or a scope path not starting at a realm vanished with the log reading zero.

   Also found and fixed en route: the principal never reached the session. The authenticator passed it as OpcUaUserAuthResult.DisplayName, but RoleCarryingUserIdentity derives DisplayName from the presented token — which for every key-bearing client is the static username apikey. So the trie's matching key was being dropped at the identity boundary, and the audit ClientUserId on a rejected write recorded apikey for every consuming system. Principal and ApiKeyId are now carried explicitly.

6. Enforce read/browse/subscribe — the new seam, with per-session decision caching.

7. AdminUI. Key management (create/revoke, show-once) ✅ done early, in stage 4's predecessor; ACL authoring against principals, and remove the two "not enforced" warning banners — which is the honest signal that this is done.

8. Rollout. Docs, the ScadaBridge key hand-off, and flipping Security:Acl:Enabled on docker-dev as the live gate.

Stage 4 live gate — PASSED (docker-dev, 2026-07-31)

Run against the six-node docker-dev rig, with site-a-1 as the subject: Cluster:Roles = driver,cluster-SITE-A, no ConnectionStrings:ConfigDb, ConfigSource:Mode=FetchAndCache. Before this stage that node registered NullOpcUaUserAuthenticator and denied every UserName token.

The key was minted with an independent Python HMAC rather than by the C# minter, so the verifier was checked against something other than itself.

#	Leg	Result
1	Boot from LocalDb cache installs an authority generation	generation 1 installed (cluster=SITE-A, revision=3f4a908c, keys=0, grants=0) — cluster identity resolved with no ConfigDb
2	Deploy a key + a SITE-A cluster grant	generation 2 installed (revision=cb165478, keys=1, grants=1); revision matches the deploy response
3	The key authenticates on the driver-only node	ApiKeyAuth: granted key Stage4 Live Gate (a1b2c3d4e5f60011) as principal stage4-gate with roles [WriteOperate]
4	A wrong secret is denied there	denied — secret mismatch for key id a1b2c3d4e5f60011
5	Revocation asymmetry, both halves	Enabled=0 in SQL, no deploy: central-1 denies on the next request (no enabled, unexpired key…) while site-a-1 still accepts. After deploying: generation 3, and site-a-1 denies. This is the documented sharp edge, observed rather than asserted.
6	Grants do not leak across clusters	site-b-1 installed keys=1, grants=0 from the same artifact — it received the key but not SITE-A's grant

Rig left clean (0 keys, 0 ACL rows, redeployed, all six nodes healthy).

Live gate (stage 8)

On docker-dev, with Security:Acl:Enabled=true:

1. A key granted ReadOnly on one equipment reads its tags and is denied a tag outside the grant.
2. The same key is denied a write; a key granted Operator writes successfully.
3. Anonymous with the setting off cannot activate a session; with it on and a ReadOnly grant, it reads and is denied writes.
4. Revoking a key denies the next request after a deploy — see the caveat below.
5. A raw-realm grant (NodeHierarchyKind.Raw) and a UNS grant both evaluate, proving blocker #1.

Known consequence to design around

Driver-only nodes have no ConfigDb (Phase 4). Keys and ACLs must therefore reach them inside the deployment artifact, exactly as NodeAcl rows already do. That means key revocation requires a deploy — there is no out-of-band revocation channel to a site node. This is a real operational sharp edge and must be documented rather than discovered; if immediate revocation is needed later, the Phase 5 gRPC telemetry stream is the existing node-reachable channel to carry it.