lmxopcua/.claude/rules/data-plane-auth.md

---
paths:
  - "src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/**"
  - "src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/**"
  - "src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/**"
  - "src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/**/*Acl*"
  - "docs/security.md"
---

# Data-plane authentication (API keys), node ACL enforcement, anonymous principal, AdminUI LDAP

> Moved verbatim from the root `CLAUDE.md` (2026-10-13) so it loads only when working in this area.
> Root `CLAUDE.md` § "Subsystem guides" indexes it. Edit it here, not in the root file.

## Authentication: API keys on the data plane, LDAP on AdminUI (#520)

⚠️ **Changed 2026-07-31. The OPC UA data plane no longer uses LDAP at all.** It is machine-to-machine,
so a client presents an OPC UA **UserName** token with the fixed username **`apikey`** and an
`otua_<keyId>_<secret>` credential as the password. `ApiKeyOpcUaUserAuthenticator`
(`src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/`) implements `IOpcUaUserAuthenticator`: one indexed lookup
on `keyId` plus one peppered HMAC-SHA256, `FixedTimeEquals`, **no network I/O**. The key resolves to a
**principal**; `NodeAcl.Principal` rows grant it permissions. `LdapOpcUaUserAuthenticator` is
**deleted**, along with four `Security:Ldap` keys that existed only for it (`AuthTimeoutMs`,
`MaxConcurrentAuthentications`, `OutageFailureThreshold`, `OutageCooldownSeconds`) — they bounded an
LDAP bind running inline in the SDK's synchronous, `SessionManager`-lock-holding impersonation
callback, and nothing on the remaining LDAP path has that property.

**LDAP remains, for AdminUI login only** (`Security:Ldap`, `OtOpcUaLdapAuthService` →
`ILdapAuthService`, group→role mapping via `GroupToRole` + `LdapGroupRoleMapping`). Do not "restore"
the data-plane authenticator when you see LDAP wiring in `Program.cs` — it is there for the AdminUI.

Two things to know before relying on any of this:

- ⚠️ **Node ACLs are enforced only behind `Security:Acl:Enabled` (default `false`).** With the flag
  **off**, a key's grants collapse into the two server-wide role gates (`WriteOperate` on Value writes,
  `AlarmAck` on Part 9 methods), **only `Cluster`-scoped grants count** — `ApiKeyInterimRoleMapper`
  deliberately under-grants, because honouring a narrower grant's flags while unable to honour its
  *scope* would turn "WriteOperate on Equipment X" into server-wide write authority — and **read,
  browse, subscribe and HistoryRead are ungated for any admitted session including Anonymous**. With the
  flag **on** (`DataPlaneAuthorizer`), scoped grants decide **every** data-plane operation: write and
  alarm commands and HistoryRead (stage 5), read and browse and subscription creation (stage 6).
  - **The two role gates re-check the session's KEY on every call, flag off or on (Gitea #563).** Roles
    are resolved once at activation, so an expired / deployment-disabled key used to keep `WriteOperate` /
    `AlarmAck` on its open session until the client disconnected. `DataPlaneAuthorizer.AuthorizeKeyUsable`
    runs the same `FindUsableKey` probe against the same snapshot + clock as the ACL path (one dictionary
    lookup, no I/O) and denies `BadUserAccessDenied` before the role check. **Only those two gates** —
    reads/subscriptions stay ungated with the flag off, by design. Anonymous carries no key and is
    unaffected. No flag: a dead key keeping write authority is a defect, not a rollout choice. ⚠️ On a
    fused node a key minted after the last deploy authenticates (ConfigDb) but cannot write/ack until a
    deployment carries it — the flag-on path always behaved this way.
  - ⚠️ **The ACL decision REPLACES the role check — the two are never chained.** Chained, a grant would
    have 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 stay inert and the flag would appear to do
    nothing. The load-bearing test is therefore an **allow** — a session carrying *no roles* writing
    successfully on the strength of its grant. A deny-only test passes against a build where the ACL is
    never consulted, because the role gate denies too.
  - **The trie is built inside `DataPlaneAuthorityState.Apply`**, not by a second wiring at the publish
    actor, and the state owns its `PermissionTrieCache` rather than being handed one. An uninstalled
    trie denies everything, which is indistinguishable from working enforcement until someone checks
    that an ALLOW is possible at all.
  - **A deploy reaches sessions that are already open**, in both directions: each decision stamps the
    *current* generation rather than the one the session activated under, and re-checks the
    authenticating key — so revoking a key or a grant stops an open session immediately instead of at
    the client's next reconnect. On a driver-only node the artifact is the only revocation channel.
  - `UserAuthorizationState` is built **per decision walk, not per session** — and since the hot-path
    change it is allocated only on a cache **miss**, so a cache hit never constructs one. Its LDAP-shaped
    freshness/staleness predicates are switched off EXPLICITLY (`AuthCacheMaxStaleness = MaxValue`).
    ⚠️ Relying on "the stamp is always fresh" was not safe: `MembershipResolvedUtc` comes from
    `DataPlaneAuthorizer`'s `TimeProvider` while `IsStale` is evaluated against
    `TriePermissionEvaluator`'s, so **any divergence between the two clocks denies every request** with a
    verdict indistinguishable from "no grant matched". Found by a test clock two hours ahead.
  - **Stage 6's hot seams (read/browse/subscribe) go through a per-`(session, node, operation, realm)`
    decision cache**, cleared wholesale when the generation advances. It is **sharded per API key**
    (`ApiKeyId ?? Principal` — despite the type name, sessions sharing one key share one shard and one
    budget), so a client crawling a large tree past the per-key ceiling evicts only that key's shard and
    not every other key's decisions. ⚠️ It caches the **grant walk only** — key revocation and expiry are
    re-checked **before** the cache lookup on every call, because expiry moves with the clock rather than
    with a deployment.
  - **Browse needs ancestor visibility, and it must NOT be a synthesized grant on the ancestors.** A
    grant deep in the tree is reached by browsing the nodes above it, and the trie inherits downward
    only, so `PermissionTrieNode.BrowseTransitPrincipals` marks the path. Planting a real `Browse` grant
    on each ancestor instead would be collected by the additive downward walk and leak `Browse` onto
    every sibling subtree beneath that ancestor. ⚠️ **The topmost ancestor is the single shared root
    folder** (`s=OtOpcUa`, raw namespace) that BOTH realm trees hang under — its identifier is a display
    name, not a path, so `DataPlaneAuthorizer.BuildScope` maps it onto the trie's **zero-segment
    realm-root scope** (`V3NodeIds.SharedRootFolderId`, realm-qualified: in the UNS namespace that
    identifier is an ordinary Area), and its Browse considers transit in **either** realm because it
    fronts both trees. Before this every narrow Browse grant was unreachable by navigation — the Browse
    gate denies the whole call when its source node is denied, so clients were stopped at the front door.
  - **Scripted-alarm commands are authorized at the OWNING EQUIPMENT, never by splitting the id (#797).**
    Production `ScriptedAlarmId`s are opaque (`^[A-Za-z0-9_-]+$`, e.g. `scripted-eqa-hi`) and become the
    condition NodeId, so `BuildScope` on them can never match an Equipment grant. Two halves, both re-read
    per call and uncached: (1) the node manager binds each live condition **instance** to its `EquipmentId`
    in `MaterialiseAlarmCondition` (only when parented under that equipment's folder; cleared on every
    teardown + rebuild); (2) the authority generation carries `EquipmentScopePaths` (built by the same
    `AclScopePathResolver` call that places Equipment grants) **and** `ScriptedAlarmOwners`
    (alarmId → EquipmentId from the artifact). `DataPlaneAuthorizer.AuthorizeScriptedCondition` denies
    unless the bound instance is the live one AND its equipment equals the generation's owner — this
    closes the install-authority-then-rebuild window and a failed apply leaving a moved alarm on its old
    equipment. ⚠️ **Fail closed, even for Cluster grants:** an unbound / replaced / undeployed / line-less
    owner is denied under every grant (no realm-root fallback). Native alarms still use RawPath; ACL-off
    is unchanged.
  - **Opaque-id UNS nodes are PLACED, never split, for every operation (#808).** UNS Area/Line/Equipment folders
    are minted under their entity ids (`s=UA-…/UL-…/EQ-…`), virtual tags under `s=EQ-…/Name`, scripted
    conditions + children under `s=<alarmId>[/…]`, while grants sit at NAME paths. `OtOpcUaNodeManager.Authorizer`'s
    setter attaches `ResolveUnsAclSubject` as `DataPlaneAuthorizer.UnsSubjectResolver` (one wiring, no second
    site), which reports LIVE facts (`UnsAclSubject`: folder id ancestry / owner binding); `Evaluate` places them
    against the CURRENT generation **before** the decision cache and caches only the walk, keyed on the resolved
    scope (`\0`-prefixed) — never on the NodeId, or a deny would stick past a rebuild. Folders use the generation's
    `UnsFolderScopes` (folderId → path + id chain, `DeploymentArtifact.BuildUnsFolderScopes`, same resolver as the
    grants; ids two kinds share are dropped) and **require live chain == generation chain** (moved equipment ⇒
    denied under old AND new line until the rebuild). Owned nodes (vtags, conditions, children) get
    `owner path + DataPlaneAuthorizer.OwnedNodeSegment` — only equipment-or-ancestor grants confer them, and a Tag
    grant's Browse transit can't enumerate them. Conditions share `TryPlaceScriptedCondition` with the #797 command
    gate, which ALSO requires the owner folder's live chain to match (review: else the new line could command a moved
    equipment's alarm while its folder is denied). Reference variables (`s=Area/Line/Equip/Name`) keep their split
    path (so Tag grants match) but only while it equals their live equipment folder's placement + one name — a
    moved/renamed equipment's old-name variables are denied (Read AND Write) under old and new names until
    re-pointed. An id NO live node holds (removed / probe / NodeDeleted `Affected`) is `Unknown`: placed at
    `[\0unknown]`, so only Cluster / Namespace-uns grants decide it and a removed opaque id can never split onto a
    same-named narrow grant — except a 4-segment (reference-shaped) id, which keeps its split. ⇒ narrow grantees do
    NOT receive NodeDeleted for removed UNS folders / vtags / conditions (by decision; they re-browse). Identifiers
    containing NUL are denied before the cache (resolved-scope keys are NUL-prefixed — a client could otherwise
    poison a real folder's cached verdict). The folder-owned rule keys on "first id segment == nearest slash-free
    live UNS folder ancestor's id", EXCEPT for a variable tracked in `_unsReferenceVariables` (the source of a
    UNS→Raw `Organizes` edge from `AddReference`), which is always a reference variable (#826 — an Area named exactly
    like its equipment's id used to make its references folder-owned). ⚠️ `ConditionVisibilityScopes` returns the
    condition ALONE for a scripted condition, so a moved alarm can't reach its old owner via the Server object — and
    since #826 not via a direct folder item either (below). A UNS node with NO live hierarchy-folder ancestor (rig-only
    shape) keeps the plain split. Unplaceable ⇒ denied for every grant incl. Cluster (a behaviour change for Cluster
    keys only in the stale window / corrupt topology). Tests: `UnsFolderScopeWireTests` (opaque ids, incl. one fed by
    `DeploymentArtifact.ParseDataPlaneAuthority`); rig tests (`ServerEventRig.FolderScopes()`, `EqA` ⇒ `[uns, EqA]`)
    install folder scopes explicitly — without them every UNS folder and scripted condition denies.
  - **Revocation reaches live subscriptions** (stage 6): every other operation re-asks per request, but a
    subscription is authorized once and then streams — and streaming is how machine consumers actually
    read this server. `DataPlaneAuthorityState.Changed` fires `RevalidateMonitoredItems`. ⚠️ A denied
    item is queued `BadUserAccessDenied` and then **detached from its `MonitoredNode2` fan-out — NOT set
    `MonitoringMode.Disabled`**: disabling discards the item's queued notifications, so the client is
    silenced without ever being told why (caught only by the over-the-wire test). Detaching is also
    reversible, so restoring the grant resumes the feed with no client action. ⚠️ **`Changed` is no longer
    the only trigger (arch-review 03/S19):** `AclRevalidationTimer`, armed by `OtOpcUaServerHostedService`
    at `Security:Acl:RevalidationIntervalSeconds` (default 60 s, `0` disables, inert while
    `Security:Acl:Enabled` is false), runs the same pass on the clock — because `ExpiresUtc` passes with
    the clock, not with a deployment. The pass's verdict memo is **pass-local and must stay that way**;
    hoisting it across ticks would serve an expiry that landed between two ticks the earlier tick's allow.
    **Event/alarm items ride both triggers too (Gitea #562)** — a second map (`_eventItems`), fed by the
    `SubscribeToEvents` override, holds every *direct* notifier subscription; a denied one is detached via
    the SDK's own protected `SubscribeToEvents(…, unsubscribe: true)` (what a client delete does) and
    re-attached with `unsubscribe: false` on restore — again never `Disabled`. Unlike a data item it is
    **not told** (no value slot for a status; the feed goes quiet), and a client delete of a stood-down
    item is absorbed by the override (the SDK would otherwise remove an item that is not attached).
    **Server-object (`i=2253`) event subscriptions are filtered per event at delivery (Gitea #586).** The
    `SubscribeToAllEvents` override attaches them to **nothing** (just records them in `_allEventsItems`);
    each condition's own `OnReportEvent` (`OnConditionReportEvent`, fires once per event ⇒ still one
    Server-object copy) queues the event to each recorded item whose session holds `Subscribe` on the
    condition (RawPath) **or** any notifier folder it reports through — the per-folder path's question. The
    root-notifier forward to the core Server object (`OnReportEvent` override) is **dropped**: it was the
    ungated path, and it is the only one that served an item created before the alarm was deployed (the
    SDK's `AddRootNotifier` subscribes existing all-events items with `unsubscribe: true`). Revalidation is
    **implicit** — every event re-asks the authorizer, so a deploy or expiry lands on the next event with no
    pass. `ConditionRefresh` on an `i=2253` item is filtered the same way. The dispatcher **must** keep
    the SDK's audit guard (`AuditEventState` only while `Server.Auditing` over SignAndEncrypt/https),
    because conditions report their Part 9 method audit events through themselves.
    `ReconcileAllEventsMonitoring` must keep `AreEventsMonitored` raised on every condition while any
    `i=2253` item exists, because `ConditionState` gates its method **audit** reports on
    `EventsMonitored()` (method-driven state-change events no longer depend on it — #587, below). The
    protected `SubscribeToEvents` override that no-ops all-events items is what
    stops the SDK's `AddRootNotifier` (`unsubscribe: true` bug) taking that unit back. Both review
    findings (review of `75e559f6`). ⚠️ The materialise path raises only the **new** condition's unit
    (`RaiseAllEventsMonitoring`); a full reconcile there made a deploy of N alarms O(N²) under `Lock` with
    ScadaBridge connected — keep the full reconcile to remove/rebuild/(un)subscribe.
    **Model-change and audit events are gated too (Gitea #588).** The manager's own server-wide events
    (`GeneralModelChangeEvent`, the rejected-write `AuditWriteUpdateEvent`) go through
    `ReportToServerObject`: flag **off** ⇒ `Server.ReportEvent` as before; flag **on** ⇒ delivered per item to
    `_allEventsItems` (same audience), a model change narrowed to the `Affected` nodes the session may
    **Browse** (dropped when none — the builders' Messages name the node, so a narrowed copy gets a neutral
    one), an audit write only with `Read` on its source node plus the SDK's audit/encryption guard. Any other
    event type fails closed. Auditing is off by default (never configured in this repo).
    **Direct (per-folder) event items are filtered per event too (Gitea #826).** The SDK's `MonitoredNode2` fan-out
    asks `INodeManager3.ValidateEventRolePermissions` per (event, item) on its own delivery task; the base method is
    NOT virtual, so `OtOpcUaNodeManager` **re-implements `INodeManager3`** and adds `IsNotifierEventVisibleTo`: the
    event's condition (snapshot handle, or an audit's SourceNode) must be the LIVE instance, the item's notifier must
    still be a legitimate notifier of it (an ancestor, or a wired folder the CURRENT generation still projects its
    RawPath into — `DataPlaneAuthoritySnapshot.TagReferencingEquipment`, from the artifact's `UnsTagReferences` via
    `AclScopePathResolver.ResolveTagRawPath`), and `IsConditionVisibleTo(item, ConditionVisibilityScopes(c))` — the
    Server-object rule, whose wired folders are ALSO generation-filtered now. ConditionRefresh on a direct item no
    longer calls the base (it uses the non-virtual base check, which bypasses the re-implementation): `RefreshDirectItems`
    mirrors the base loop plus the same decision. Since #855 condition events at our notifiers are served per item,
    per event, UNCACHED by `DeliverToNotifierItems` (the same three checks, resolved once per hop), never through the
    SDK channel. ⚠️ **#878: the SDK channel's verdict is a flat DENY under enforcement.** The SDK memoizes whatever
    `INodeManager3.ValidateEventRolePermissions` returns per `(item, eventType, SourceNode)` until the monitored node's
    permission generation moves (item add/remove, rebind, namespace default-permission change — NOT a deploy or grant
    change); #826 kept it fresh with reflection into the SDK's private `MonitoredNode2.InvalidatePermissionCaches`
    (`InvalidateFolderEventVerdicts`, a detach/re-attach fallback, a guard test). All of it is DELETED: its only caller
    in SDK 2.0.1 is `MonitoredNode2.GetOrAddEventPermissionAsync`, and only a condition's SDK-raised method AUDITS ride
    that channel (auditing on + SignAndEncrypt + `SecurityAdmin`, the one role the SDK type check admits to audit types
    — nothing grants it) or a hand-made `folder.ReportEvent` (none in src). Denying them all keeps the cached verdict
    grant-independent. **Do not reintroduce a grant-dependent decision on that path** — it would need the invalidation
    back. Residual: a flag-OFF allow survives the switch to ON (authorizer wired just after server start). Mutation
    record: with the invalidation disabled only its own counter test and a flag-off→on plain-event test failed (347
    integration tests). Tests: `FolderEventVerdictFreshnessTests`. ⚠️ The verdict is decided on the LIVE instance
    holding the event's condition NodeId, never the event's own instance (a replaced instance's late event is treated as
    the live one's).
    `TagReferencingEquipment` holds ALARM-BEARING tags only (`TagConfigIntent.Alarm`). ⚠️ A hand-built
    authority (rigs) must pass `tagReferencingEquipment` or native alarms stop reaching equipment-folder items under
    enforcement (`ServerEventRig.TagReferences()`); null ⇒ none (fail closed). Tests:
    `UnsFolderScopeWireTests.A_moved_alarm_stops_reaching_its_old_folders_subscribers…`,
    `NativeAlarmFolderEventAclWireTests`.
    ⚠️ **Never report an event with the synchronous `NodeState.ReportEvent` while holding `Lock` (#838).** Each
    notifier's `MonitoredNode2` drains a BOUNDED channel (4096, `FullMode = Wait`) and its delivery task takes `Lock` on a
    verdict-cache miss (SDK `GetNodeMetadata` — flag off too — and #826's check); sync `ReportEvent` blocks on a full
    channel ⇒ a >4096 burst under one `Lock` hold deadlocked the node manager (stalled at 4097). Condition events go
    through `ReportEventWithoutBlocking`: our own copy of the SDK walk with a LIVENESS check before every hop (and in
    `OnConditionReportEvent`) — a deferred event of a removed/replaced condition is dropped, never a ghost on `i=2253`;
    per-CONDITION ordered queues on overflow; coalesce past 1024/condition or 65 536 total (oldest not-started gives way
    to newest); Warning/Information + `otopcua.opcua.condition_events.{deferred,discarded}`. A Server-object ConditionRefresh
    (and ConditionRefresh2, #854) with nothing deferred is the plain walk OFF `Lock`; while deferring it takes a sequence
    CUT (one short `Lock` hold: watermark + frozen snapshots of Retain conditions from `_alarmConditions`), queues the
    replay off `Lock` one event per hold of a per-item gate, and withholds older deferred events from THAT item only
    (re-sent condition, or Retain=true of one omitted because NOT retained — never one omitted by ACL). Item state is a
    `ConditionalWeakTable` keyed by the item; cuts clear when the deferral count hits 0. Tests:
    `ConditionRefreshDeferralWireTests`. ⚠️ **Since #855 folder items are delivered per item too:** at every notifier we own, `DeliverConditionEventAsync` serves the `MonitoredNode2`'s attached items itself (`DeliverToNotifierItems`: audit guard → `INodeManager3.ValidateEventRolePermissions` per event, UNCACHED → item gate/cut → `QueueEvent`), never through the SDK channel — so no notifier of ours defers, a flood under `Lock` defers nothing, and folder refreshes (`RefreshDirectItems`, flag on AND off) share the #854 cut. The deferral queue + cut remain as the safety net; an event whose walk suspends is marked deferred BEFORE suspending. Tests produce deferral with `NotifierStall` (the `NotifierDeliveryStall` probe) — holding a folder item's SDK lock now blocks the reporter. `FolderConditionRefreshWireTests`; `docs/plans/2026-11-11-folder-event-per-item-delivery.md`. Because that queueing runs under `Lock`, event item queues are `RingEventMonitoredItemQueue` (#870, supplied by `OtOpcUaSdkServer.CreateMonitoredItemQueueFactory` via `RingEventQueueFactory`; data-change queues stay the SDK's) — the SDK queue's discard-oldest was a `List.RemoveAt(0)` per stalled item per report. It is storage only (overflow events + DiscardOldest live in the SDK's unchanged `EventQueueHandler`); parity pinned by `RingEventMonitoredItemQueueParityTests` — re-check them on an SDK bump. Folder events follow Part 3's shape —
    `ReceiveEvents` on EventType + SourceNode (SDK check, kept first) AND our decision; non-condition events on a
    folder item fail closed under enforcement. Tests: `FolderEventFloodWireTests`. Overflow WITH the ACL doing work (#838
    item 2) — denied condition interleaved, folder + `i=2253` items, non-publishing client, concurrent Read, grant revoked
    while a deferred tail waits — is `EventQueueOverflowAclWireTests`: the item-queue overflow is the SDK's DiscardOldest
    (newest kept, one `EventQueueOverflowEventType` ahead of the survivors); deferred events are decided at DELIVERY, so a
    revocation stops the waiting tail; events already in the item queue when a grant is revoked may still publish (authorized when queued).
- **ns=0 standard nodes stay ungated by design, even with `Security:Acl:Enabled`** (#617) — `ServerStatus`,
  `NamespaceArray`, `ServiceLevel` etc. are served by the SDK's core node manager outside our authorizer and
  clients read them to connect and to judge redundancy health; they carry no plant data. Every raw/UNS node,
  event subscription and HistoryRead is still gated. `docs/security.md`.
- **Equipment-node writes: `EvaluateEquipmentWriteStructure` is the ONLY type check.** `OnWriteValue` bypasses
  the SDK's own type check on every writable equipment node, so `OtOpcUaNodeManager.EvaluateEquipmentWriteStructure`
  (plus `EvaluateEquipmentWriteRange`) is the whole gate. Scalars are deliberately lenient (drivers
  range-check; ScadaBridge sends Double to a Float node). **Array writes** (#610): a numeric array of another
  element type is **converted, checked, element by element** to the node's element type (ScadaBridge writes
  CLR `int[]`/`double[]` lists) — any out-of-range, fractional-to-integer or NaN/∞ element refuses the whole
  write `BadTypeMismatch` with nothing sent, so a `UInt32` > `Int32.MaxValue` can never reach a Galaxy Int32
  attribute as reinterpreted bits; non-numeric mismatches are refused (`Byte[]` ≈ ByteString); wrong length ⇒
  `BadTypeMismatch`; an array to a **scalar** node is refused only on Modbus/S7 (`EnsureVariable`'s
  `refuseArrayOnScalar` — pass-through drivers keep their browse-committed scalar-shaped array tags writable;
  a new sink wrapper must forward that argument, and the reflection guard checks only that the call arrives);
  `IndexRange` writes ⇒ `BadWriteNotSupported`, `ValueRank > 1` out of scope. An
  array node is writable only when the driver can write the array (`DriverArrayWriteSupport`: Modbus keys-addressed tags bounded
  by `maxRegistersPerWrite` (never above FC16's 123)/coil cap/address 65535 incl. String/BitInRegister arrays
  (BitInRegister also by `maxRegistersPerRead`: its RMW is one unchunked FC03) (#741; a string-only `addressString` tag
  stays read-only — family unknown at compose time), S7 non-Bool/non-wide types, OpcUaClient, Galaxy signed types **with a
  declared `arrayLength`** — an undeclared length stays read-only because a short whole-array write would
  resize the Galaxy attribute; AbCip atomic non-BOOL types, AbLegacy Int/Long/Float on the matching data file
  (no `/bit`/`.sub`/indirect/`S:`/`I:`/`O:`, not native PLC-5, ≤ 256), TwinCAT every codec type but a BOOL
  bit-in-word path — #737/#738/#739; those three CONVERT elements, so they never key on an exact node type); `arrayLength >= 1` is required, and the node's `Writable && (!IsArray ||
  ArrayWritable)` is projected onto the raw node and every UNS mirror.
- **Anonymous is a normal grantable principal**, not a bypass. `OpcUa:AllowAnonymous` (default `true`,
  preserving today's behaviour) controls *admission*; when admitted the session authenticates as the
  reserved principal `anonymous` and gets roles from `NodeAcl` rows naming it, arriving at the gates as
  the same `RoleCarryingUserIdentity` a key produces. Set it `false` to make keys mandatory. A key may
  **not** use the `anonymous` principal, and a failure to read anonymous's grants **denies** rather
  than admitting with no roles.
- ⚠️ **The SDK's failed-auth lockout is OFF; ours is UserName-only (#833).** SDK 2.0.1 `SessionManager` refuses
  EVERY activation (Anonymous included, before the token is read) from a client with 5 failures in 60 s, for 5 min,
  keyed cert-thumbprint-else-peer-IP. `OpcUaApplicationHost.DisableSdkAuthenticationLockout` zeroes
  `MaxFailedAuthenticationAttempts` on built AND loaded configs; `FailedCredentialLockout` (`OpcUa:CredentialLockout`,
  5 / 60 s / 300 s) counts and refuses UserName activations only, keyed thumbprint+peer together. Do not re-enable the
  SDK setting. The check takes a verification SLOT (`BeginAsync`/`Complete`/`Abandon`) — a check and a
  separate record let a parallel burst through. At most `max − failures` verify at once; the rest WAIT (never refused
  for parallelism — ScadaBridge opens many keyed sessions from one IP), refused only on lockout or, uncounted, after
  `SlotWaitSeconds`. An expired lockout resets the count. On
  `None` endpoints the key is effectively IP-only (NAT neighbours share it, UserName only). ⚠️ **Two counts (#844):**
  per (client, CANONICAL credential identity = `IOpcUaUserAuthenticator.DescribeCredential`, `key:<keyId>` trimmed +
  lower-cased, non-hex ids folded together, since SQL `=` is CI/trailing-space-blind / `user:<name>`),
  cleared by a success with THAT identity, locks that identity; per client (`MaxFailedAttemptsPerClient`, default
  2 × max) — **never reset by a success** (else a valid key launders guesses at another key id) — locks every
  credential. ⚠️ **Only definite bad credentials count (#845):** store timeout / miss-budget / store throw / unset
  pepper / authenticator throw / cancel ⇒ `OpcUaUserAuthResult.Unavailable` (`Transient`) ⇒ `Abandon`, uncounted.
  ApplicationUri is deliberately NOT in the key (free string on `None` ⇒ trivial evasion). `docs/security.md`
  §"Failed-credential lockout".
- **Keys reach a driver-only node inside the deployment artifact** (stage 4). `ConfigComposer` snapshots
  the `ApiKey` rows — the peppered HMAC only, never a secret, and the pepper is node config that is
  deliberately *not* in the artifact — and `DeploymentArtifact.ParseDataPlaneAuthority` decodes them
  node-side alongside the cluster's `NodeAcl` rows. `OpcUaPublishActor` installs both on
  `IDataPlaneAuthoritySource` on every apply, **before** its `plan.IsEmpty` early-return, so a deployment
  that only revokes a key still lands. A node with a ConfigDb keeps `ConfigDbApiKeyStore` (per-activation
  read, wrapped — see below); a driver-only node gets `ArtifactApiKeyStore`. ⚠️ **The asymmetry is
  ACTIVATION-scoped, not session-scoped — this line used to say "immediate on a ConfigDb node" and that was
  wrong.** Clearing `Enabled` in the ConfigDb stops the **next session activation** on an admin/fused node
  (bounded by `Security:ApiKeys:StoreCacheSeconds`, default 5 s) and takes until the next deployment on a
  driver-only one — but an **already-open** session re-checks its key against the in-memory *artifact
  snapshot* (`DataPlaneAuthorizer.Evaluate` → `snapshot.FindUsableKey`), never against `IApiKeyStore`, so on
  **both** node kinds an `Enabled` revocation reaches an open session only at the next deployment.
  **Expiry is the exception**: `FindUsableKey` compares `ExpiresUtc` against the authorizer's clock on every
  call, so it is immediate everywhere — and since arch-review 03/S19 it reaches live subscriptions too, on
  the host's `Security:Acl:RevalidationIntervalSeconds` timer (default 60 s; the session is **silenced with
  `BadUserAccessDenied`, not closed**, and recovers on re-activation). Direct event/alarm subscriptions
  are revalidated on both triggers as well (#562); with the flag **off**, expiry and revocation reach the
  two role gates (#563) but not reads or subscriptions.
- ⚠️ **The activation lookup is BOUNDED (arch-review 03/S18).** The SDK raises impersonation synchronously
  under a `SessionManager`-wide lock, so a ConfigDb that is *slow* rather than *refusing* stalled **every**
  session activation on the server, Anonymous and X.509 included. `BoundedApiKeyStore` wraps the ConfigDb
  store — and only it, never `ArtifactApiKeyStore`, which is two in-memory dictionary probes — with
  `Security:ApiKeys:StoreTimeoutMs` (2000; exceeding it **denies**, via the authenticator's existing
  catch-all) plus a `StoreCacheSeconds` (5) read-through cache. Faults and timeouts are never cached, a
  cached hit whose `ExpiresUtc` has passed is re-read rather than served, and a timeout logs a distinct
  Warning + `otopcua.opcua.apikey_store.bounded{outcome=timeout}`. Both knobs at `0` restore the old
  behaviour exactly.
- ⚠️ **The auth generation is a node-local COUNTER driven by the `RevisionHash`, not derived from its
  bits.** `PermissionTrieCache` treats the highest `GenerationId` as current, so a generation taken from
  hash bytes would install a *lower* number about half the time and the cache would go on serving the
  previous deployment's ACLs with nothing logged. Pinned by
  `DataPlaneAuthorityStateTests.The_generation_only_ever_increases_even_when_the_hash_decreases`.
- Note `OtOpcUaServerHostedService` takes `IOpcUaUserAuthenticator` **and** `IDataPlaneAuthoritySource`
  as **required** ctor parameters — the built-in DI container does not fall back to a default value for
  an unregistered service, so both must be registered explicitly on every node (deny-all / empty on a
  node with neither role) or it does not boot.

**Grants are authored through a scope picker, not free text (stage 7).** `/clusters/{id}/acls` opens
`AclScopePickerModal` over the cluster's raw + UNS trees, and selecting a node supplies `ScopeKind`
**and** `ScopeId` together — so `RawDevice` + a TagId, a cross-cluster scope, a `Cluster` grant carrying
an id, and the retired `FolderSegment` kind are all unauthorable by construction rather than merely
rejected later. ⚠️ **A `Cluster` row must produce a NULL `ScopeId`** — the deploy gate rejects one that
carries an id (`NodeAclScopeIdUnexpected`), so a picker that helpfully filled in the cluster id would
author rows that cannot be deployed. `IAclScopeService.CheckScopeAsync` mirrors
`DraftValidator.ValidateNodeAclScopes` rule for rule and **blocks the save** when a scope resolves to
nothing (re-checked on submit, since a row loaded unchanged is exactly where the operator never touches
the picker); the list page marks such rows `unresolved`. **UNS tags are deliberately not offered** — a
UNS signal is a `UnsTagReference`, and a `Tag` grant already covers the raw node *and* every UNS
projection of it. The picker is `AclScopeTree`, a separate component from `RawTree`, which already
carries two modes.

**All eight stages are done** (`d4389f57` enforcement, stage 7 authoring after it), each live-gated on
docker-dev. The rationale for every decision above is in
`docs/plans/2026-07-31-apikey-acl-enforcement-design.md`. See `docs/security.md` for the full guide.

Dev/test LDAP is the **shared GLAuth** running on the Linux Docker host at `10.100.0.35:3893` (baseDN `dc=zb,dc=local`, plaintext/`Transport=None`). It is managed via `scadaproj/infra/glauth/` (source of truth + deploy runbook). Single bind account `cn=serviceaccount,dc=zb,dc=local` / `serviceaccount123`; all test users password `password`. The docker-dev compose binds this shared instance directly — `DevStubMode` is no longer used. The per-VM NSSM GLAuth at `C:\publish\glauth\` and the old base DNs `dc=lmxopcua,dc=local` / `dc=otopcua,dc=local` are obsolete. (The integration-test harness under `tests/.../Host.IntegrationTests/` runs its own ephemeral **GLAuth** container on port 3894 — seeded by `tests/.../Host.IntegrationTests/glauth/config.toml` with dev users alice/bob + the `cn=serviceaccount` bind account — for the opt-in `OTOPCUA_HARNESS_USE_LDAP=1` real-bind mode; distinct from the shared dev GLAuth on 3893. It replaced the retired `bitnami/openldap:2.6` in PR #451, 2026-07-15.)