fix(acl): place opaque-id UNS folders, virtual tags and scripted conditions for every operation (#808)

UNS Area/Line/Equipment folders are minted under their opaque entity ids
(s=UA-/UL-/EQ-...), virtual tags under s=EQ-.../Name and scripted conditions
(+ #629 children) under s=<ScriptedAlarmId>[/...], while every UNS grant is
planted at a NAME path. DataPlaneAuthorizer split those ids, so with
Security:Acl:Enabled a narrow (Area/Line/Equipment) grant could not Browse,
Read, subscribe or HistoryRead them, and Server-object delivery never reached
it — so a narrow key never held the EventId Ack/Confirm/AddComment need.

- The generation carries UnsFolderScopes (folderId -> path + id chain), built
  by DeploymentArtifact from the same AclScopePathResolver as the grants; ids
  two entity kinds share are dropped; plumbed through IDataPlaneAuthoritySink.
- OtOpcUaNodeManager.ResolveUnsAclSubject reports live facts (folder id
  ancestry / scripted owner binding); attached by the Authorizer setter.
- Evaluate places the subject against the CURRENT generation before the
  decision cache, which now caches the walk keyed on the resolved scope.
  Folders require live chain == generation chain (a moved equipment is denied
  under old and new line until the rebuild). Owned nodes (vtags, conditions,
  children) get owner path + a reserved segment, so Tag grants and their
  Browse transit never expose them. Conditions share TryPlaceScriptedCondition
  with the #797 command gate.
- Server-object visibility of a scripted condition is decided on the
  condition alone, so a moved alarm cannot reach its old owner there.

Tests: UnsFolderScopeWireTests (opaque ids, end-to-end browse -> EventId ->
Acknowledge on an Equipment grant; sibling denied; Tag-only grant; moved alarm
and moved equipment stale windows). Rig tests now install folder scopes
explicitly (ServerEventRig.FolderScopes); the #797 recreate test deliberately
asserts the moved alarm is invisible to the Cluster observer in the window.
This commit is contained in:
Joseph Doherty
2026-11-10 23:12:46 -05:00
parent 308b1b3b56
commit af5c9744b7
15 changed files with 1095 additions and 60 deletions
@@ -36,7 +36,8 @@ public sealed class DataPlaneAuthoritySnapshot
IReadOnlyDictionary<string, ApiKey> keysById,
IReadOnlyDictionary<string, IReadOnlyList<NodeAcl>> grantsByPrincipal,
IReadOnlyDictionary<string, NodeAclPath> equipmentScopePaths,
IReadOnlyDictionary<string, string> scriptedAlarmOwners)
IReadOnlyDictionary<string, string> scriptedAlarmOwners,
IReadOnlyDictionary<string, UnsFolderScope> unsFolderScopes)
{
ClusterId = clusterId;
RevisionHash = revisionHash;
@@ -49,6 +50,7 @@ public sealed class DataPlaneAuthoritySnapshot
_grantsByPrincipal = grantsByPrincipal;
EquipmentScopePaths = equipmentScopePaths;
ScriptedAlarmOwners = scriptedAlarmOwners;
UnsFolderScopes = unsFolderScopes;
}
private readonly IReadOnlyDictionary<string, ApiKey> _keysById;
@@ -131,6 +133,69 @@ public sealed class DataPlaneAuthoritySnapshot
return true;
}
/// <summary>
/// <c>UNS folder id → (its ACL path, its folder-id chain)</c> for every UNS Area, Line and Equipment in the
/// artifact this generation was built from (Gitea #808). Keyed <c>OrdinalIgnoreCase</c> (identifier rule).
/// </summary>
/// <remarks>
/// <para>
/// <b>Why this exists.</b> The address space mints UNS Area / Line / Equipment folders under their opaque
/// entity ids (<c>s=UA-…</c>, <c>s=UL-…</c>, <c>s=EQ-…</c>) — and an equipment's virtual tags under
/// <c>s=EQ-…/Name</c> — while every UNS grant is planted at a NAME path
/// (<c>[uns, Area, Line, Equipment]</c>). Splitting such a NodeId can never reach a narrow grant, so the
/// authorizer resolves the folder id to its path HERE instead, against the same generation as the grants.
/// </para>
/// <para>
/// <see cref="UnsFolderScope.IdChain"/> is the folder's ancestry as THIS generation deploys it
/// (<c>[areaId, lineId, equipmentId]</c>). The authorizer requires the LIVE folder's ancestry to equal it:
/// the generation is installed before its address space is applied, and an apply that throws keeps the
/// old address space, so a folder moved to another line would otherwise be authorized at its new path
/// while it still hangs under the old one. A mismatch denies until the address space catches up.
/// </para>
/// <para>
/// An entry confers nothing and is never consulted by the trie build. A folder absent here (an orphan
/// line, a line-less equipment, an id two entity kinds share) has no path, and every node resolved
/// through it is denied under enforcement.
/// </para>
/// </remarks>
public IReadOnlyDictionary<string, UnsFolderScope> UnsFolderScopes { get; }
/// <summary>
/// The ACL path WITHIN the UNS realm (realm segment stripped) of the UNS folder <paramref name="folderId"/>,
/// provided the live folder's ancestry <paramref name="liveIdChain"/> is exactly the one this generation
/// deploys. False (the caller must deny) when the folder is unknown, misshapen or placed differently.
/// </summary>
/// <param name="folderId">The folder's id (its <c>s=</c> identifier).</param>
/// <param name="liveIdChain">The live folder ancestry, root-first, ending at <paramref name="folderId"/>.</param>
/// <param name="unsSegments">The path below the realm root, e.g. <c>[Area, Line, Equipment]</c>.</param>
/// <returns><see langword="true"/> when the folder is known and placed as this generation deploys it.</returns>
public bool TryGetUnsFolderSegments(
string folderId, IReadOnlyList<string> liveIdChain, out IReadOnlyList<string> unsSegments)
{
unsSegments = [];
if (string.IsNullOrEmpty(folderId) || liveIdChain is null || liveIdChain.Count == 0) return false;
if (!string.Equals(liveIdChain[^1], folderId, StringComparison.OrdinalIgnoreCase)) return false;
if (!UnsFolderScopes.TryGetValue(folderId, out var scope)) return false;
// Shape-checked rather than trusted, as TryGetEquipmentUnsSegments is: a path that does not start at the
// UNS realm, or names the realm alone, places nothing — accepting it would evaluate at the realm root.
if (scope.Path.Segments.Count < 2
|| !string.Equals(scope.Path.Segments[0], NodeAclRealms.Uns, StringComparison.Ordinal)
|| scope.IdChain.Count != scope.Path.Segments.Count - 1
|| scope.IdChain.Count != liveIdChain.Count)
{
return false;
}
for (var i = 0; i < liveIdChain.Count; i++)
{
if (!string.Equals(scope.IdChain[i], liveIdChain[i], StringComparison.OrdinalIgnoreCase)) return false;
}
unsSegments = scope.Path.Segments.Skip(1).ToArray();
return true;
}
/// <summary>
/// The cluster this node belongs to per the artifact's <c>ClusterNode</c> row, or null on a
/// single-cluster / legacy artifact where no scoping applies.
@@ -212,6 +277,8 @@ public sealed class DataPlaneAuthoritySnapshot
/// null ⇒ none, which denies every scripted-condition command under enforcement.</param>
/// <param name="scriptedAlarmOwners"><c>ScriptedAlarmId → EquipmentId</c> as this generation deploys them
/// (see <see cref="ScriptedAlarmOwners"/>); null ⇒ none.</param>
/// <param name="unsFolderScopes">Every UNS folder's path + id chain (see <see cref="UnsFolderScopes"/>);
/// null ⇒ none, which denies every UNS folder-scoped node under enforcement.</param>
/// <returns>The built snapshot.</returns>
public static DataPlaneAuthoritySnapshot Create(
string? clusterId,
@@ -222,7 +289,8 @@ public sealed class DataPlaneAuthoritySnapshot
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths,
IReadOnlyList<PermissionTrieBuildDiagnostic>? droppedGrants = null,
IReadOnlyDictionary<string, NodeAclPath>? equipmentScopePaths = null,
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null)
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null,
IReadOnlyDictionary<string, UnsFolderScope>? unsFolderScopes = null)
{
ArgumentNullException.ThrowIfNull(revisionHash);
ArgumentNullException.ThrowIfNull(keys);
@@ -279,12 +347,37 @@ public sealed class DataPlaneAuthoritySnapshot
}
}
var folders = new Dictionary<string, UnsFolderScope>(StringComparer.OrdinalIgnoreCase);
if (unsFolderScopes is not null)
{
foreach (var (folderId, scope) in unsFolderScopes)
{
if (string.IsNullOrWhiteSpace(folderId) || scope?.Path is null || scope.IdChain is null) continue;
// A case-variant duplicate can only come from a corrupt input; mark it unplaceable rather than let
// iteration order decide which placement authorizes.
if (!folders.TryAdd(folderId, scope)) folders[folderId] = UnsFolderScope.Unplaceable;
}
}
return new DataPlaneAuthoritySnapshot(
clusterId, revisionHash, generationId, keys, grants, scopePaths, droppedGrants ?? [], byId, frozen,
equipment, owners);
equipment, owners, folders);
}
}
/// <summary>
/// Where one UNS Area / Line / Equipment folder sits, as a generation deploys it (Gitea #808).
/// </summary>
/// <param name="Path">Its ACL path, <c>[uns, Area(, Line(, Equipment))]</c> — the exact path a grant on that
/// entity is planted at.</param>
/// <param name="IdChain">Its folder-id ancestry, root-first, ending at the folder itself
/// (<c>[areaId, lineId, equipmentId]</c>) — one id per path segment below the realm.</param>
public sealed record UnsFolderScope(NodeAclPath Path, IReadOnlyList<string> IdChain)
{
/// <summary>A placement no live folder can match (a realm-only path) — the deny marker for a corrupt duplicate.</summary>
public static readonly UnsFolderScope Unplaceable = new(new NodeAclPath([NodeAclRealms.Uns]), []);
}
/// <summary>Read side of the node's current data-plane authorization inputs.</summary>
public interface IDataPlaneAuthoritySource
{
@@ -351,6 +444,8 @@ public interface IDataPlaneAuthoritySink
/// the owner lookup for scripted alarm conditions (Gitea #797). Null ⇒ none.</param>
/// <param name="scriptedAlarmOwners"><c>ScriptedAlarmId → EquipmentId</c> as the same artifact deploys
/// them (Gitea #797 review). Null ⇒ none, which denies every scripted-condition command under enforcement.</param>
/// <param name="unsFolderScopes">Every UNS Area/Line/Equipment folder's path + id chain from the same
/// artifact (Gitea #808). Null ⇒ none, which denies every UNS folder-scoped node under enforcement.</param>
/// <returns>The installed snapshot.</returns>
DataPlaneAuthoritySnapshot Apply(
string? clusterId,
@@ -359,7 +454,8 @@ public interface IDataPlaneAuthoritySink
IReadOnlyList<NodeAcl> grants,
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths,
IReadOnlyDictionary<string, NodeAclPath>? equipmentScopePaths = null,
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null);
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null,
IReadOnlyDictionary<string, UnsFolderScope>? unsFolderScopes = null);
}
/// <summary>
@@ -409,7 +505,8 @@ public sealed class DataPlaneAuthorityState : IDataPlaneAuthoritySource, IDataPl
IReadOnlyList<NodeAcl> grants,
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths,
IReadOnlyDictionary<string, NodeAclPath>? equipmentScopePaths = null,
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null)
IReadOnlyDictionary<string, string>? scriptedAlarmOwners = null,
IReadOnlyDictionary<string, UnsFolderScope>? unsFolderScopes = null)
{
ArgumentNullException.ThrowIfNull(revisionHash);
@@ -443,7 +540,7 @@ public sealed class DataPlaneAuthorityState : IDataPlaneAuthoritySource, IDataPl
published = DataPlaneAuthoritySnapshot.Create(
clusterId, revisionHash, generation, keys, grants, scopePaths, dropped, equipmentScopePaths,
scriptedAlarmOwners);
scriptedAlarmOwners, unsFolderScopes);
Volatile.Write(ref _current, published);
}