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

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

**Status:** implemented through stage 7 — **#520 CLOSED 2026-08-01**. Stage merges: `fbe7403c`
(stages 1-2, 4: API-key identity + keys/ACLs via the artifact), `3a6b2a1d` (stage 3: variable-depth
scope model + scopePaths producer), `1ccc7400`/`f692f6af` (stage 5: enforcement on write, alarms,
HistoryRead), `d4389f57`/`00aa4866` (stage 6: enforcement on read, browse, subscribe), `3796c0bf`
(stage 7: ACL scope picker + authoring-time resolution). Enforcement is opt-in via
`Security:Acl:Enabled` (default `false`). *(Was: "design agreed 2026-07-31, not yet implemented" —
corrected 2026-08-07, truth sweep.)*
**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.~~ **Closed** —
  stage 3 gave it a deploy-time existence check, and stage 7 an authoring-time one plus a picker that
  cannot produce a dangling id. There is still no FK: `ScopeId` names a row in one of eight tables
  chosen by `ScopeKind`, which is not a foreign key any schema can express.
- ~~`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 substituted for the ACL scope picker until
   stage 7 shipped one; it remains the backstop for rows edited outside the AdminUI.
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.** ✅ **Done.** `Read`, `Browse`, `TranslateBrowsePath`,
   `CreateMonitoredItems`, `SubscribeToEvents` and `SetMonitoringMode` are gated at the node manager;
   `SessionAclDecisionCache` memoizes the grant walk per `(session, node, operation, realm)` and flushes
   on a generation change.

   Four things went differently from this line, all deliberate:

   - **Browse needed a new trie concept: ancestor visibility.** The trie inherits downward, and a client
     reaches a deep node by browsing the nodes above it — so without this, every grant narrower than the
     cluster was authored, stored, shipped and *unreachable*. ⚠️ The obvious implementation, planting a
     synthetic `Browse` grant on each ancestor, is a silent widening: the additive downward walk carries
     it from `Plant` onto `Plant/Siemens/dev9` and every other sibling subtree. It is a separate,
     non-inheriting marker (`BrowseTransitPrincipals`) checked at the exact node only, set only by grants
     that actually carry `Browse`, and conferring only `Browse`. The consequence to accept: the *names*
     of the folders on the path to a granted node are visible to whoever holds that grant.
   - **The cache holds the grant walk, not the decision.** Grants and the trie are fixed for a
     generation; a key's `ExpiresUtc` passes with the clock. Caching the whole decision would have let an
     expired key keep working until the next deploy — the stage-5 open-session hole in a subtler form.
   - **Revocation had to reach LIVE subscriptions, which needed a push.** Every other operation re-asks
     per request; a subscription is authorized once and streams. Since subscriptions are how machine
     consumers actually read this server, stopping only the re-asking operations would have made
     revocation close to cosmetic. `IDataPlaneAuthoritySource` gained a `Changed` event and the node
     manager re-authorizes every live item on it. ⚠️ A denied item is queued `BadUserAccessDenied` and
     then **detached from its node's fan-out, not set `MonitoringMode.Disabled`** — disabling *discards
     queued notifications*, silencing the client without telling it why. Caught by the over-the-wire test
     rather than by reasoning; the unit-level path reports the item as stood down either way. Detaching
     is also reversible, so a restored grant resumes the feed with no client action.
   - **`TranslateBrowsePath` is gated too**, without which browse filtering is decorative: a client
     refused a browse would ask `TranslateBrowsePathsToNodeIds` for the same path and get the NodeId.

   Also found and fixed en route: **`UserAuthorizationState`'s staleness ceiling couples two clocks.**
   `MembershipResolvedUtc` is stamped from `DataPlaneAuthorizer`'s `TimeProvider` while `IsStale` is
   evaluated against `TriePermissionEvaluator`'s. They are the same instance in production and diverge
   the moment anything injects a test clock — at which point the evaluator denies *everything* with a
   verdict indistinguishable from "no grant matched". Stage 5's claim that these predicates "can never
   fire" was accidentally true, not true by construction; they are now disabled explicitly.
7. **AdminUI.** ✅ **Done.** Key management (create/revoke, show-once) landed early, in stage 4's
   predecessor. This stage added the **scope picker** (`AclScopePickerModal` over the cluster's raw and
   UNS trees, backed by `IAclScopeService`), authoring-time **scope and principal resolution**, and
   reshaped the two banners.

   Four things went differently from this line, all deliberate:

   - **The banners were reshaped, not removed.** "Remove the two warning banners" assumed the only thing
     they said was *not enforced*, which stage 6 falsified. What remains true is that enforcement is a
     **per-node** flag the AdminUI cannot see, so an `Equipment`-scoped grant still confers nothing on a
     default-configured node — deleting the banner would have replaced one wrong impression with
     another. They are now `alert-info` describing both modes, flag-on first.
   - **The picker sets the kind AND the id, and there is no longer a hand-edit path.** The plan asked
     for "a `RawTree` picker for `ScopeId`", which would have left the kind dropdown beside it and kept
     `RawDevice` + a TagId authorable. Selecting a tree node supplies both, which makes
     `NodeAclScopeCrossCluster`, `NodeAclScopeIdUnexpected`, `NodeAclScopeIdMissing` and
     `NodeAclScopeKindRetired` unauthorable by construction rather than merely discouraged.
   - **It is a new component, not a third mode on `RawTree`.** `RawTree` already carries the `/raw`
     editing tree and the equipment reference picker. A third mode would put the scope picker's bugs on
     the device-authoring page, and with no bUnit in this repo the only thing that would catch that is
     someone noticing. `AclScopeTree` renders a unified `AclScopeNode` instead, which is also what lets
     ONE component serve both hierarchies — `RawTree` covers only the raw side.
   - **Saving is blocked on an unresolved scope, and the list page marks the rot.** Not asked for; it is
     what closes `ScopeId` dangling silently (the open item at the top of this doc) rather than moving
     the discovery from deploy time to slightly-earlier deploy time. The check re-runs on submit rather
     than trusting the verdict from when the form loaded, because a row loaded unchanged is exactly the
     case where the operator never touches the picker.

   Also fixed en route: the ACL editor had a `DataAnnotationsValidator` and **no `ValidationSummary`**,
   so an invalid `NodeAclId` made the Create button a silent no-op — the [[project_adminui_no_bunit_live_verify]]
   failure mode, present in this page since it was written.
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 — PASSED (docker-dev, 2026-08-01)

Subject: **site-a-1** (`driver,cluster-SITE-A`, no ConfigDb, `ConfigSource:Mode=FetchAndCache`) with
`Security:Acl:Enabled=true`. Control: **central-1**, same artifact, flag unset. All six nodes were
rebuilt onto the gate commit first and image parity asserted per container, because `:9200`
round-robins central-1/central-2 and a stale central-2 rejected the deploy outright (`Cannot convert
string value 'RawDevice' … enum` — its image predated the stage-3 scope kinds).

The key was minted with an **independent Python HMAC**, so the verifier was checked against something
other than itself. One grant throughout: `RawDevice` → `SITEA-dev`, i.e. `raw/sa-modbus2/plc`.

| # | Leg | Result |
|---|---|---|
| 0 | The grant is *placed*, not dropped | `generation 2 installed (keys=1, grants=1, resolvedScopes=1)`, no dropped-rule warning. This is the leg that distinguishes working enforcement from a trie that silently denies everything |
| 1 | Read INSIDE the grant | `Value: 16100, Status: 0x00000000` |
| 2 | Read OUTSIDE it (sibling device `plc2`) | `BadUserAccessDenied` |
| 3 | Browse the driver, gated | `plc` only — `plc2` filtered out |
| 4 | Browse the same driver on the **control** | `plc` **and** `plc2` — the A/B that shows the filtering is the ACL and not the address space |
| 5 | Browse the ungranted device directly | `BadUserAccessDenied` (the throw path) |
| 6 | Anonymous on the gated node | `BadUserAccessDenied` — principal `anonymous` holds no grant |
| 7 | Write with a grant lacking `WriteOperate` | `0x801F0000` |
| 8 | Same write after granting `WriteOperate` (+redeploy) | `Write successful` |
| 9 | Wrong secret | `BadIdentityTokenRejected` at activation |
| 10 | **Revoke mid-subscription** | see below |
| 11 | **Restore the grant** | see below |

Legs 10–11 are the ones worth reading as a transcript, because they are what stage 6 added and what
no offline test could settle:

```
13:49:39  SiteAOnly = 53   (0x00000000)     ← streaming, ~1/s
13:49:40  SiteAOnly =      (0x801F0000)     ← the revoking deployment lands; the client is TOLD
          … 25 seconds of complete silence — ~25 updates that did not arrive …
13:50:05  SiteAOnly = 157  (0x00000000)     ← the restoring deployment lands; the feed resumes
```

Note `53 → 157`: the device counter ran throughout, so it was **delivery** that stopped, not the
source. The `0x801F0000` frame is the half that the `MonitoringMode.Disabled` implementation would
have swallowed.

**Not proven by this gate:** a UNS-realm grant (the rig's SITE-A cluster has no UNS equipment), and
alarm-command scoping (no alarms configured on SITE-A). Both are covered offline; neither has been
seen live. Reads on the *control* node returned `BadNodeIdUnknown` rather than a value — central does
not materialise another cluster's tag variables — so leg 4's browse is the meaningful A/B, not a read.

**Found en route, unrelated to ACLs:** the rig's `SITEA-modbus` driver had an empty `DriverConfig`, so
its factory rejected the config and the driver ran as a stub serving nothing. Fixed on the rig
(`Host`/`Port` added) — without it every read returns `BadWaitingForInitialData` and the allow legs
cannot be told from a denial.

Rig left as found: key, ACL row, the second device and its tag all deleted and redeployed; site-a
returned to `Security:Acl:Enabled` unset, confirmed by the absence of the startup banner and an
anonymous read succeeding again.

## Stage 7 live gate — PASSED (docker-dev, 2026-08-01)

Driven through the AdminUI at `:9200` against cluster **SITE-A**. Both central containers were asserted
to be running the same freshly-built image *by container id*, not from one `docker compose build` — the
stale-central-2 trap from the stage-6 gate.

| # | Leg | Result |
|---|---|---|
| 1 | Picker lazily expands the real raw tree | ✅ cluster → `sa-modbus2` → `plc` → `SiteAOnly`, one level per expand |
| 2 | Each level offers its own scope kind | ✅ `CLUSTER` / `RAWDRIVER` / `RAWDEVICE` / `TAG` chips |
| 3 | Selecting a node sets kind **and** id | ✅ → `RAWDEVICE` + `SITEA-dev`, "✓ Device 'plc' in cluster 'SITE-A'" |
| 4 | Principal reaching nobody warns | ✅ `not-a-real-principal` → ⚠ "No active API key uses this principal" |
| 5 | …and the positive control | ✅ `anonymous` → ✓ "The reserved anonymous principal" |
| 6 | Grant saves and lists with its resolved target | ✅ |
| 7 | A rotted row is marked on the list | ✅ id broken by SQL → `UNRESOLVED` chip + reason |
| 8 | Saving a rotted row is **blocked** | ✅ "Scope: No device in this configuration has the id …" |
| 9 | Re-picking a valid scope unblocks it | ✅ `NAMESPACE raw` → saved |
| 10 | The authored grant **deploys** | ✅ `POST /api/deployments` → `Sealed` |
| 11 | The deploy gate rejects what the page rejects | ✅ same row broken by SQL → HTTP 422 `NodeAclScopeUnresolved` |
| 12 | UNS column offers area / line / equipment | ✅ `UNSAREA` / `UNSLINE` / `EQUIPMENT`, eager, after a UNS was authored under SITE-A |
| 13 | Selecting an equipment resolves | ✅ `EQUIPMENT` + `EQ-f3dd0e8e27a4`, "✓ Equipment 'packer-1' in cluster 'SITE-A'" |
| 14 | A UNS-realm grant deploys | ✅ `Sealed` |
| 15 | A cross-cluster scope is caught at both ends | ✅ re-pointed at MAIN's equipment → list marks it `UNRESOLVED` naming `MAIN`; deploy → HTTP 422 `NodeAclScopeCrossCluster` |

Legs 8 and 11 are the pair that matters: the page and the deploy gate reject the same row for the same
reason, which is the claim "`CheckScopeAsync` mirrors `DraftValidator`" reduces to. Leg 11 also
confirmed the *kind* is honoured on both sides — the row was re-pointed at `RawDriver`, and the gate's
message named `DriverInstance`.

Legs 5 and 9 are the positive controls. Without them the gate passes against a page that refuses
everything, which is the same failure shape stage 6's `resolvedScopes=N` leg exists to catch.

Legs 12–15 were added in a second pass after authoring a UNS (area → line → equipment) under SITE-A,
which had none when the first pass ran. **Leg 15 is the one worth keeping:** it is the only rejection
whose id is *real*, so a check that asked only "does a row with this id exist?" would accept it and
confer authority across a cluster boundary. Both ends name the owning cluster.

**Found while authoring that UNS, unrelated to this stage:** the `/uns` **area** and **line** modals do
**not** validate the UNS segment format, so "Packaging" and "Line 1" saved happily and then failed the
deploy with `UnsSegmentInvalid` — fleet-wide, since a deployment snapshots the whole database, so one
bad area name blocks every cluster's deploy. Only `EquipmentPage.razor:570` carries the
`^[a-z0-9-]{1,32}$` rule. Exactly the authoring-vs-gate gap this stage closed for ACLs. Filed
separately; not fixed here.

Rig state afterwards: the gate's ACL rows deleted and a further deployment sealed, leaving SITE-A at
zero ACL rows as found. The **UNS structure was kept** (area `packaging` → line `line-1` → equipment
`packer-1`, renamed to valid segments), since SITE-A having a UNS is what made legs 12–15 possible and
keeps them re-runnable.

## 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.