feat(acl): variable-depth scope model + the scopePaths producer (#520 stage 3)
Makes the /raw device tree addressable by an ACL rule, and builds the
scope-path producer PermissionTrieBuilder has accepted since it was written
but which had no caller anywhere.
The plan for this stage said "add NodeHierarchyKind.Raw, whose path is the
RawPath segments Folder/Driver/Device/TagGroup/Tag". That shape is wrong.
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 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,
Segments} and the walk is a segment loop. The trie STRUCTURE was already
variable-depth (NodeAclPath.Segments is a list, 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 gated on NodeScope.NamespaceId,
but v3 has no Namespace entity — the snapshot was retired when the address
space went dual-namespace, and the identifier appears nowhere in production
outside NodeScope. So the level could only ever fail to match, which silently
made every sub-cluster grant unreachable while cluster grants kept working.
It is now a realm token derived from the scope's Kind, not carried on it, so
the walk and the producer cannot disagree about its spelling.
- Provenance comes from the granting row's own ScopeKind, recorded on TrieGrant
at build time. Depth-derived provenance could not name a raw level at all,
since the depth of "Device" varies with folder nesting.
- 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.
- 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. scopePaths is
now required, and a row that does not resolve is dropped with a diagnostic.
A scope resolves to a LIST of paths: 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 covering only the raw node would be
bypassable through a UNS one. The lookup is keyed on (ScopeKind, ScopeId), not
ScopeId alone — ScopeId has no FK and no type discriminator, so an id collision
across entity types would hand a grant the wrong node's paths.
Also closed here, all found by review rather than asked for:
- NodeAcl rows had no deploy-time validation of any kind and were not reachable
from DraftValidator at all (DraftSnapshot carried no NodeAcls). They are now
gated for dangling ids, cross-cluster scopes, blank/contradictory ScopeId, the
retired FolderSegment kind, and undefined ordinals.
- ConfigDbApiKeyStore conferred roles from Cluster-scoped grants authored in ANY
cluster, because it filtered on scope kind with no ClusterId predicate while
ArtifactApiKeyStore read an already-cluster-filtered snapshot. On a fused
admin+driver node that was a cross-cluster over-grant. Its doc comment claimed
the two stores matched.
- The two AdminUI ACL banners still said enforcement was LDAP-group -> role
mapping, which stages 1/2 made false in both directions.
- The /apikeys page was never classified in PageAuthorizationGuardTests, so that
test has been red since the key-minting commit merged — I did not run
AdminUI.Tests before merging stage 4.
Falsified rather than assumed: 8 mutations against the trie tests, 5 against the
deploy gate (including one proving a cross-cluster row is not silently
mis-diagnosed as unresolved), a staged red->green for the over-grant regression,
and the realm gate, the comparer and the malformed-path guard each broken
individually to confirm only their own tests go red.
Node ACLs are still not ENFORCED — nothing constructs a NodeScope or calls the
evaluator yet. That is stages 5 and 6; this stage makes the model able to
express what those will enforce.
Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
This commit is contained in:
Joseph Doherty
@@ -1,18 +1,62 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
|
||||
/// <summary>ACL scope level. Per <c>acl-design.md</c> §"Scope Hierarchy".</summary>
|
||||
/// <remarks>
|
||||
/// ⚠️ <b>Append new members only — never insert.</b> SQL Server stores this as a string
|
||||
/// (<c>nvarchar(16)</c>, so a member name must also stay ≤ 16 characters), but the deployment
|
||||
/// artifact serialises it as the <b>integer ordinal</b> and the node-side decoder reads it back
|
||||
/// with <c>Enum.IsDefined</c>. Inserting a member mid-enum silently re-maps every grant in every
|
||||
/// already-deployed artifact to a different scope level.
|
||||
/// </remarks>
|
||||
public enum NodeAclScopeKind
|
||||
{
|
||||
/// <summary>The whole cluster — the only kind that carries a null <c>ScopeId</c>.</summary>
|
||||
Cluster,
|
||||
Namespace,
|
||||
UnsArea,
|
||||
UnsLine,
|
||||
Equipment,
|
||||
|
||||
/// <summary>
|
||||
/// A folder segment anchored below a namespace (used for FolderPath-scoped tags).
|
||||
/// Distinguishes folder grants from UNS <see cref="Equipment"/> grants in the
|
||||
/// <c>AuthorizationDecision.Provenance</c> audit trail and Admin UI diagnostics.
|
||||
/// One whole OPC UA namespace (realm). <c>ScopeId</c> is the realm token <c>raw</c> or
|
||||
/// <c>uns</c>; see <c>NodeAclRealms</c>, which is the single authority for that spelling.
|
||||
/// </summary>
|
||||
Namespace,
|
||||
|
||||
/// <summary>A UNS area. <c>ScopeId</c> is a <c>UnsArea.UnsAreaId</c>.</summary>
|
||||
UnsArea,
|
||||
|
||||
/// <summary>A UNS line. <c>ScopeId</c> is a <c>UnsLine.UnsLineId</c>.</summary>
|
||||
UnsLine,
|
||||
|
||||
/// <summary>A UNS equipment. <c>ScopeId</c> is an <c>Equipment.EquipmentId</c>.</summary>
|
||||
Equipment,
|
||||
|
||||
/// <summary>
|
||||
/// ⚠️ <b>Retired v2 concept — do not author new rows with this kind.</b> It described a folder
|
||||
/// segment under the v2 <c>SystemPlatform</c>/Galaxy hierarchy, which v3 deleted along with the
|
||||
/// <c>WalkSystemPlatform</c> walker. The v3 replacement is <see cref="RawFolder"/>. The member
|
||||
/// survives only because removing it would shift every later ordinal in already-deployed
|
||||
/// artifacts; a row still carrying it resolves no scope path and is reported as an unresolved
|
||||
/// scope by the deploy gate.
|
||||
/// </summary>
|
||||
FolderSegment,
|
||||
|
||||
/// <summary>
|
||||
/// A single tag. <c>ScopeId</c> is a <c>Tag.TagId</c> — i.e. a <b>raw</b> tag, which is the only
|
||||
/// kind of tag v3 has. Because one raw tag can be projected into several equipments by
|
||||
/// <c>UnsTagReference</c> rows, a Tag-scoped grant resolves to <b>several</b> trie paths: the raw
|
||||
/// node plus every UNS projection of it. That is deliberate — a write routes to the same driver
|
||||
/// reference through either NodeId, so a grant that covered only one of them would be bypassable
|
||||
/// through the other.
|
||||
/// </summary>
|
||||
Tag,
|
||||
|
||||
/// <summary>A raw-tree folder. <c>ScopeId</c> is a <c>RawFolder.RawFolderId</c>. (v3; appended.)</summary>
|
||||
RawFolder,
|
||||
|
||||
/// <summary>A raw-tree driver instance. <c>ScopeId</c> is a <c>DriverInstance.DriverInstanceId</c>. (v3; appended.)</summary>
|
||||
RawDriver,
|
||||
|
||||
/// <summary>A raw-tree device. <c>ScopeId</c> is a <c>Device.DeviceId</c>. (v3; appended.)</summary>
|
||||
RawDevice,
|
||||
|
||||
/// <summary>A raw-tree tag group. <c>ScopeId</c> is a <c>TagGroup.TagGroupId</c>. (v3; appended.)</summary>
|
||||
RawTagGroup,
|
||||
}
|
||||
|
||||
@@ -62,6 +62,10 @@ public sealed class DraftSnapshot
|
||||
/// <summary>Gets the list of poll groups.</summary>
|
||||
public IReadOnlyList<PollGroup> PollGroups { get; init; } = [];
|
||||
|
||||
/// <summary>ACL grants. Drive the scope-resolution rule: a scope that names nothing deployed is
|
||||
/// silently dropped when the permission trie is built, so the grant has to be caught here instead.</summary>
|
||||
public IReadOnlyList<NodeAcl> NodeAcls { get; init; } = [];
|
||||
|
||||
/// <summary>Prior Equipment rows (any generation, same cluster) for stability checks.</summary>
|
||||
public IReadOnlyList<Equipment> PriorEquipment { get; init; } = [];
|
||||
|
||||
|
||||
@@ -52,6 +52,7 @@ public static class DraftSnapshotFactory
|
||||
ScriptedAlarms = await db.ScriptedAlarms.AsNoTracking().ToListAsync(ct),
|
||||
Scripts = await db.Scripts.AsNoTracking().ToListAsync(ct),
|
||||
PollGroups = await db.PollGroups.AsNoTracking().ToListAsync(ct),
|
||||
NodeAcls = await db.NodeAcls.AsNoTracking().ToListAsync(ct),
|
||||
PriorEquipment = [], // intentional: no prior-generation table to diff against at this level
|
||||
ActiveReservations = await db.ExternalIdReservations
|
||||
.AsNoTracking()
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
using System.Text.RegularExpressions;
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.Types;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
@@ -42,9 +43,235 @@ public static class DraftValidator
|
||||
ValidateEquipReferenceResolution(draft, errors);
|
||||
ValidateCalculationTags(draft, errors);
|
||||
ValidateSqlConnectionStringNotPersisted(draft, errors);
|
||||
ValidateNodeAclScopes(draft, errors);
|
||||
return errors;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// #520 stage 3: every <see cref="NodeAcl"/> row's scope must name something the deployed address
|
||||
/// space actually contains.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// ACL rows have had <b>no</b> validation anywhere until now, and the failure mode is the worst
|
||||
/// shape a security control can have: <c>AclScopePathResolver</c> returns no path for a scope it
|
||||
/// cannot resolve, the trie builder then drops the grant with a build-time diagnostic, and the
|
||||
/// deploy still seals green. An operator who mistypes a <c>ScopeId</c>, or scopes a grant at an
|
||||
/// entity someone later deleted, gets a row that reads as a live grant in the AdminUI and
|
||||
/// authorizes nothing at runtime. Silently dropping a grant is fail-closed and therefore safe,
|
||||
/// but it is not <em>visible</em> — which is why the check belongs at the deploy gate, where the
|
||||
/// author is still standing in front of the mistake.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The realm tokens are duplicated here, deliberately.</b> <c>NodeAclRealms</c> in
|
||||
/// <c>Core.Authorization</c> is the authority for their spelling, but <c>Core</c> references
|
||||
/// <c>Configuration</c> and not the reverse, so this project cannot reach it. The two namespace
|
||||
/// <em>URIs</em> come from <see cref="V3NodeIds"/> in <c>Commons</c>, which both sides do share;
|
||||
/// only the two short tokens are literals. If a third realm is ever added, it must be added in
|
||||
/// both places — the accepted cost of not inverting the project graph for one gate.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Existence is checked with the same ordinal, untrimmed comparison
|
||||
/// <c>AclScopePathResolver</c>'s dictionary lookups use, so a row this rule passes is a row that
|
||||
/// resolver resolves. The realm check mirrors <c>NodeAclRealms.TryCanonicalize</c> instead
|
||||
/// (trimmed, case-insensitive) for the same reason.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Containment is checked as well as existence.</b> A grant in cluster A naming an entity that
|
||||
/// belongs to cluster B is not the "names nothing" failure — it resolves to a real trie path, and
|
||||
/// so it silently confers authority across a cluster boundary. It gets its own code because the
|
||||
/// remedy is different: an unresolved id is a typo or a deletion, a cross-cluster id is a grant
|
||||
/// authored against the wrong cluster. The lookups are deliberately <b>fleet-wide, not
|
||||
/// cluster-filtered</b> — a per-cluster lookup would make a cross-cluster id present as merely
|
||||
/// unresolved, which is the wrong diagnosis and would leave this check unable to ever fire.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Ownership is not a uniform property. <c>RawFolder</c>, <c>DriverInstance</c> and <c>UnsArea</c>
|
||||
/// carry <c>ClusterId</c>; <c>Device</c>, <c>TagGroup</c>, <c>Tag</c>, <c>UnsLine</c> and
|
||||
/// <c>Equipment</c> do not, and inherit it through their parent. Both chains are at most three
|
||||
/// hops and neither can loop (<c>TagGroup</c> and <c>RawFolder</c> nest, but both reach the
|
||||
/// cluster through a non-nesting link — <c>DeviceId</c> and <c>ClusterId</c> respectively), so
|
||||
/// unlike the resolver's ancestry walks these need no depth guard. A broken chain means the
|
||||
/// owning cluster is unknowable, which is the same state as unresolvable: it reports
|
||||
/// <c>NodeAclScopeUnresolved</c> and never both codes.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
private static void ValidateNodeAclScopes(DraftSnapshot draft, List<ValidationError> errors)
|
||||
{
|
||||
if (draft.NodeAcls.Count == 0) return;
|
||||
|
||||
// One map per ancestry link, built once for the whole pass. Their key sets double as the existence
|
||||
// sets, so "does this id name a row of the kind's type" and "which cluster owns it" cannot disagree.
|
||||
// GroupBy/First rather than ToDictionary: a duplicated id is another rule's business, and throwing
|
||||
// here would take down every remaining check in the same pass.
|
||||
var folderCluster = Link(draft.RawFolders, f => f.RawFolderId, f => f.ClusterId);
|
||||
var driverCluster = Link(draft.DriverInstances, d => d.DriverInstanceId, d => d.ClusterId);
|
||||
var deviceDriver = Link(draft.Devices, d => d.DeviceId, d => d.DriverInstanceId);
|
||||
var groupDevice = Link(draft.TagGroups, g => g.TagGroupId, g => g.DeviceId);
|
||||
var tagDevice = Link(draft.Tags, t => t.TagId, t => t.DeviceId);
|
||||
var areaCluster = Link(draft.UnsAreas, a => a.UnsAreaId, a => a.ClusterId);
|
||||
var lineArea = Link(draft.UnsLines, l => l.UnsLineId, l => l.UnsAreaId);
|
||||
var equipLine = Link(draft.Equipment, e => e.EquipmentId, e => e.UnsLineId);
|
||||
|
||||
static Dictionary<string, string> Link<T>(
|
||||
IReadOnlyList<T> rows, Func<T, string> key, Func<T, string> value) =>
|
||||
rows.GroupBy(key, StringComparer.Ordinal)
|
||||
.ToDictionary(g => g.Key, g => value(g.First()), StringComparer.Ordinal);
|
||||
|
||||
// Owning cluster, or null when a link in the chain is dangling. Direct-ClusterId kinds bottom out
|
||||
// immediately; the rest hop through their parent.
|
||||
string? ClusterOfDevice(string deviceId) =>
|
||||
deviceDriver.TryGetValue(deviceId, out var driverId) ? driverCluster.GetValueOrDefault(driverId) : null;
|
||||
string? ClusterOfLine(string lineId) =>
|
||||
lineArea.TryGetValue(lineId, out var areaId) ? areaCluster.GetValueOrDefault(areaId) : null;
|
||||
|
||||
foreach (var acl in draft.NodeAcls)
|
||||
{
|
||||
var id = acl.NodeAclId;
|
||||
|
||||
// An ordinal outside the enum comes from a hand-edited row or a schema the code no longer
|
||||
// matches. Every later check switches on the kind, so nothing below it would be meaningful.
|
||||
if (!Enum.IsDefined(acl.ScopeKind))
|
||||
{
|
||||
errors.Add(new("NodeAclScopeKindUndefined",
|
||||
$"NodeAcl '{id}' has ScopeKind ordinal {(int)acl.ScopeKind}, which is not a defined " +
|
||||
"NodeAclScopeKind; the row cannot be evaluated. Re-author it with a valid scope kind.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (acl.ScopeKind == NodeAclScopeKind.Cluster)
|
||||
{
|
||||
// Cluster is the one kind with nothing to point at, so a ScopeId here means the author
|
||||
// intended a narrower scope and picked the wrong kind — the grant is cluster-wide either
|
||||
// way, i.e. broader than intended, which is the direction that must never pass silently.
|
||||
if (!string.IsNullOrWhiteSpace(acl.ScopeId))
|
||||
errors.Add(new("NodeAclScopeIdUnexpected",
|
||||
$"NodeAcl '{id}' is Cluster-scoped but carries ScopeId '{acl.ScopeId}'. A Cluster grant " +
|
||||
"covers the whole cluster and ignores ScopeId; clear it, or change ScopeKind to the level " +
|
||||
"the id names.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
// Ahead of the missing-ScopeId check on purpose: the retirement is the actionable fact, and
|
||||
// telling someone to supply a ScopeId for a kind that can never resolve sends them the wrong way.
|
||||
if (acl.ScopeKind == NodeAclScopeKind.FolderSegment)
|
||||
{
|
||||
errors.Add(new("NodeAclScopeKindRetired",
|
||||
$"NodeAcl '{id}' uses the retired v2 scope kind FolderSegment, which has no v3 entity behind " +
|
||||
"it and can never resolve, whatever its ScopeId. Re-scope the grant to RawFolder (the v3 " +
|
||||
"replacement) and point ScopeId at the RawFolderId that replaced the old folder segment.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(acl.ScopeId))
|
||||
{
|
||||
errors.Add(new("NodeAclScopeIdMissing",
|
||||
$"NodeAcl '{id}' has ScopeKind {acl.ScopeKind} but no ScopeId. Only Cluster grants may omit " +
|
||||
"it; every other kind resolves no scope path without one and the grant is dropped at build " +
|
||||
"time. Set the ScopeId, or change ScopeKind to Cluster.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
var scopeId = acl.ScopeId!;
|
||||
|
||||
if (acl.ScopeKind == NodeAclScopeKind.Namespace)
|
||||
{
|
||||
if (CanonicalRealm(scopeId) is null)
|
||||
errors.Add(new("NodeAclNamespaceInvalid",
|
||||
$"NodeAcl '{id}' is Namespace-scoped but ScopeId '{scopeId}' names no OPC UA namespace. " +
|
||||
$"Use '{RealmRaw}' or '{RealmUns}' (or the full URI '{V3NodeIds.RawNamespaceUri}' / " +
|
||||
$"'{V3NodeIds.UnsNamespaceUri}').",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
// Each arm names the entity type the kind's ScopeId is drawn from, whether a row with that id
|
||||
// exists at all, and which cluster owns it. Switch arms evaluate lazily, so only the matched
|
||||
// kind's chain is walked.
|
||||
var (entity, exists, owner) = acl.ScopeKind switch
|
||||
{
|
||||
NodeAclScopeKind.UnsArea =>
|
||||
("UnsArea", areaCluster.ContainsKey(scopeId), areaCluster.GetValueOrDefault(scopeId)),
|
||||
NodeAclScopeKind.UnsLine =>
|
||||
("UnsLine", lineArea.ContainsKey(scopeId), ClusterOfLine(scopeId)),
|
||||
NodeAclScopeKind.Equipment =>
|
||||
("Equipment", equipLine.ContainsKey(scopeId),
|
||||
equipLine.TryGetValue(scopeId, out var eqLine) ? ClusterOfLine(eqLine) : null),
|
||||
NodeAclScopeKind.Tag =>
|
||||
("Tag", tagDevice.ContainsKey(scopeId),
|
||||
tagDevice.TryGetValue(scopeId, out var tagDev) ? ClusterOfDevice(tagDev) : null),
|
||||
NodeAclScopeKind.RawFolder =>
|
||||
("RawFolder", folderCluster.ContainsKey(scopeId), folderCluster.GetValueOrDefault(scopeId)),
|
||||
NodeAclScopeKind.RawDriver =>
|
||||
("DriverInstance", driverCluster.ContainsKey(scopeId), driverCluster.GetValueOrDefault(scopeId)),
|
||||
NodeAclScopeKind.RawDevice =>
|
||||
("Device", deviceDriver.ContainsKey(scopeId), ClusterOfDevice(scopeId)),
|
||||
NodeAclScopeKind.RawTagGroup =>
|
||||
("TagGroup", groupDevice.ContainsKey(scopeId),
|
||||
groupDevice.TryGetValue(scopeId, out var grpDev) ? ClusterOfDevice(grpDev) : null),
|
||||
|
||||
// Cluster / Namespace / FolderSegment all returned above; the undefined case did too.
|
||||
_ => (string.Empty, true, acl.ClusterId),
|
||||
};
|
||||
|
||||
if (!exists)
|
||||
{
|
||||
errors.Add(new("NodeAclScopeUnresolved",
|
||||
$"NodeAcl '{id}' is scoped at {acl.ScopeKind} '{scopeId}', which is not a {entity} in this " +
|
||||
"configuration. The grant would be dropped at build time and authorize nothing. Correct the " +
|
||||
"ScopeId, or delete the grant if the entity was removed.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (owner is null)
|
||||
{
|
||||
// The row exists but its parent chain is dangling, so it has no place in any cluster's tree
|
||||
// and resolves to no path — the same outcome as a missing row, reported under the same code.
|
||||
errors.Add(new("NodeAclScopeUnresolved",
|
||||
$"NodeAcl '{id}' is scoped at {acl.ScopeKind} '{scopeId}', which exists but whose parent " +
|
||||
$"chain is broken, so no cluster owns it and it resolves to no scope path. Repair the {entity}'s " +
|
||||
"parent reference, or delete the grant.",
|
||||
id));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!string.Equals(owner, acl.ClusterId, StringComparison.Ordinal))
|
||||
errors.Add(new("NodeAclScopeCrossCluster",
|
||||
$"NodeAcl '{id}' is a grant in cluster '{acl.ClusterId}' but is scoped at {acl.ScopeKind} " +
|
||||
$"'{scopeId}', which belongs to cluster '{owner}'. The id is real, so the grant would resolve " +
|
||||
"and confer authority across a cluster boundary. Re-author the grant under cluster " +
|
||||
$"'{owner}', or point ScopeId at the matching {entity} in '{acl.ClusterId}'.",
|
||||
id));
|
||||
}
|
||||
}
|
||||
|
||||
// Realm tokens — see ValidateNodeAclScopes for why these are duplicated rather than referenced.
|
||||
// Core.Authorization.NodeAclRealms is the authority; keep the two in step.
|
||||
private const string RealmRaw = "raw";
|
||||
private const string RealmUns = "uns";
|
||||
|
||||
/// <summary>Mirror of <c>NodeAclRealms.TryCanonicalize</c>: accepts either short realm token or either
|
||||
/// full namespace URI, trimmed and case-insensitive. Null when the id names no realm.</summary>
|
||||
private static string? CanonicalRealm(string scopeId)
|
||||
{
|
||||
var trimmed = scopeId.Trim();
|
||||
|
||||
if (string.Equals(trimmed, RealmRaw, StringComparison.OrdinalIgnoreCase)
|
||||
|| string.Equals(trimmed, V3NodeIds.RawNamespaceUri, StringComparison.OrdinalIgnoreCase))
|
||||
return RealmRaw;
|
||||
|
||||
if (string.Equals(trimmed, RealmUns, StringComparison.OrdinalIgnoreCase)
|
||||
|| string.Equals(trimmed, V3NodeIds.UnsNamespaceUri, StringComparison.OrdinalIgnoreCase))
|
||||
return RealmUns;
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The <c>Sql</c> driver's "a pasted literal connection string is never persisted" guarantee, enforced
|
||||
/// at the deploy gate (Gitea #498).
|
||||
|
||||
@@ -0,0 +1,288 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.Types;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
|
||||
/// <summary>
|
||||
/// Identifies a scope for path lookup. Keyed on the kind <b>as well as</b> the id.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The kind is part of the key because <c>NodeAcl.ScopeId</c> is a bare string with no foreign key
|
||||
/// and no type discriminator of its own — ids are prefixed by convention (<c>RF…</c>, <c>EQ…</c>)
|
||||
/// but nothing enforces it. Keying on the id alone would let a <c>DeviceId</c> that happened to
|
||||
/// equal a <c>UnsAreaId</c> hand a grant the other entity's paths, which is a silent
|
||||
/// wrong-node authorization rather than a visible error.
|
||||
/// </remarks>
|
||||
/// <param name="Kind">The authored scope kind.</param>
|
||||
/// <param name="ScopeId">The authored scope id.</param>
|
||||
public readonly record struct AclScopeRef(NodeAclScopeKind Kind, string ScopeId);
|
||||
|
||||
/// <summary>
|
||||
/// Produces the <c>scopePaths</c> lookup <see cref="PermissionTrieBuilder.Build"/> consumes: for each
|
||||
/// ACL scope, the trie path(s) at which a grant on it must be planted (#520 stage 3).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Pure and input-shape agnostic, in the same spirit as <see cref="RawPathResolver"/>: callers
|
||||
/// build the ancestry maps from whatever they hold — EF entities on the authoring / deploy-gate
|
||||
/// side, artifact JSON on the node side — so both sides produce identical paths without sharing a
|
||||
/// database. That matters because a driver-only node has no ConfigDb at all (per-cluster mesh
|
||||
/// Phase 4), so anything requiring a DB read node-side is disqualified outright.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Raw tag paths are delegated to <see cref="RawPathResolver"/> rather than recomputed, so an ACL
|
||||
/// path and the RawPath that forms the node's actual NodeId cannot drift apart. Container paths
|
||||
/// (folder / driver / device / group) are composed here from the same chains in the same order,
|
||||
/// which keeps every container path a true prefix of the tags beneath it — the property the trie
|
||||
/// walk depends on for a container grant to cascade.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// A broken or dangling link yields <b>no path</b> for that scope, never a throw: the grant is then
|
||||
/// dropped by the builder with an <see cref="PermissionTrieBuildDiagnosticReason.UnresolvedScope"/>
|
||||
/// diagnostic. Fail-closed, and consistent with the resolver family's "a malformed artifact drops
|
||||
/// one entry rather than faulting the whole decode" rule.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class AclScopePathResolver
|
||||
{
|
||||
private readonly IReadOnlyDictionary<string, (string? ParentId, string Name)> _folders;
|
||||
private readonly IReadOnlyDictionary<string, (string? RawFolderId, string Name)> _drivers;
|
||||
private readonly IReadOnlyDictionary<string, (string DriverInstanceId, string Name)> _devices;
|
||||
private readonly IReadOnlyDictionary<string, (string? ParentId, string DeviceId, string Name)> _groups;
|
||||
private readonly IReadOnlyDictionary<string, (string DeviceId, string? TagGroupId, string Name)> _tags;
|
||||
private readonly IReadOnlyDictionary<string, string> _areas;
|
||||
private readonly IReadOnlyDictionary<string, (string UnsAreaId, string Name)> _lines;
|
||||
private readonly IReadOnlyDictionary<string, (string UnsLineId, string Name)> _equipment;
|
||||
private readonly IReadOnlyList<(string EquipmentId, string TagId, string EffectiveName)> _references;
|
||||
private readonly RawPathResolver _rawPaths;
|
||||
|
||||
/// <summary>Initializes a new <see cref="AclScopePathResolver"/> over the deployed topology.</summary>
|
||||
/// <param name="folders"><c>RawFolderId → (ParentRawFolderId?, Name)</c>.</param>
|
||||
/// <param name="drivers"><c>DriverInstanceId → (RawFolderId?, Name)</c>.</param>
|
||||
/// <param name="devices"><c>DeviceId → (DriverInstanceId, Name)</c>.</param>
|
||||
/// <param name="groups"><c>TagGroupId → (ParentTagGroupId?, DeviceId, Name)</c>.</param>
|
||||
/// <param name="tags"><c>TagId → (DeviceId, TagGroupId?, Name)</c>.</param>
|
||||
/// <param name="areas"><c>UnsAreaId → Name</c>.</param>
|
||||
/// <param name="lines"><c>UnsLineId → (UnsAreaId, Name)</c>.</param>
|
||||
/// <param name="equipment"><c>EquipmentId → (UnsLineId, Name)</c>.</param>
|
||||
/// <param name="references">The UNS projections: <c>(EquipmentId, TagId, EffectiveName)</c>.</param>
|
||||
public AclScopePathResolver(
|
||||
IReadOnlyDictionary<string, (string? ParentId, string Name)> folders,
|
||||
IReadOnlyDictionary<string, (string? RawFolderId, string Name)> drivers,
|
||||
IReadOnlyDictionary<string, (string DriverInstanceId, string Name)> devices,
|
||||
IReadOnlyDictionary<string, (string? ParentId, string DeviceId, string Name)> groups,
|
||||
IReadOnlyDictionary<string, (string DeviceId, string? TagGroupId, string Name)> tags,
|
||||
IReadOnlyDictionary<string, string> areas,
|
||||
IReadOnlyDictionary<string, (string UnsAreaId, string Name)> lines,
|
||||
IReadOnlyDictionary<string, (string UnsLineId, string Name)> equipment,
|
||||
IReadOnlyList<(string EquipmentId, string TagId, string EffectiveName)> references)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(folders);
|
||||
ArgumentNullException.ThrowIfNull(drivers);
|
||||
ArgumentNullException.ThrowIfNull(devices);
|
||||
ArgumentNullException.ThrowIfNull(groups);
|
||||
ArgumentNullException.ThrowIfNull(tags);
|
||||
ArgumentNullException.ThrowIfNull(areas);
|
||||
ArgumentNullException.ThrowIfNull(lines);
|
||||
ArgumentNullException.ThrowIfNull(equipment);
|
||||
ArgumentNullException.ThrowIfNull(references);
|
||||
|
||||
_folders = folders;
|
||||
_drivers = drivers;
|
||||
_devices = devices;
|
||||
_groups = groups;
|
||||
_tags = tags;
|
||||
_areas = areas;
|
||||
_lines = lines;
|
||||
_equipment = equipment;
|
||||
_references = references;
|
||||
|
||||
_rawPaths = new RawPathResolver(
|
||||
folders,
|
||||
drivers,
|
||||
devices,
|
||||
groups.ToDictionary(kv => kv.Key, kv => (kv.Value.ParentId, kv.Value.Name), StringComparer.Ordinal));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Resolve the trie path(s) for every distinct scope named by <paramref name="rows"/>. Scopes that
|
||||
/// resolve to nothing are absent from the result, which is what makes the builder drop them.
|
||||
/// </summary>
|
||||
/// <param name="rows">The ACL rows whose scopes need resolving.</param>
|
||||
/// <returns>The <c>scopePaths</c> lookup.</returns>
|
||||
public IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> Resolve(IReadOnlyList<NodeAcl> rows)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
|
||||
var result = new Dictionary<AclScopeRef, IReadOnlyList<NodeAclPath>>();
|
||||
|
||||
foreach (var row in rows)
|
||||
{
|
||||
if (row.ScopeKind == NodeAclScopeKind.Cluster || string.IsNullOrEmpty(row.ScopeId)) continue;
|
||||
|
||||
var key = new AclScopeRef(row.ScopeKind, row.ScopeId);
|
||||
if (result.ContainsKey(key)) continue;
|
||||
|
||||
var paths = ResolveOne(row.ScopeKind, row.ScopeId);
|
||||
if (paths.Count > 0) result[key] = paths;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/// <summary>Resolve one scope to its trie path(s). Empty when the scope names nothing deployed.</summary>
|
||||
/// <param name="kind">The scope kind.</param>
|
||||
/// <param name="scopeId">The scope id.</param>
|
||||
/// <returns>The resolved paths, possibly empty.</returns>
|
||||
public IReadOnlyList<NodeAclPath> ResolveOne(NodeAclScopeKind kind, string scopeId)
|
||||
{
|
||||
if (string.IsNullOrEmpty(scopeId)) return [];
|
||||
|
||||
switch (kind)
|
||||
{
|
||||
case NodeAclScopeKind.Namespace:
|
||||
var realm = NodeAclRealms.TryCanonicalize(scopeId);
|
||||
return realm is null ? [] : [new NodeAclPath([realm])];
|
||||
|
||||
case NodeAclScopeKind.UnsArea:
|
||||
return _areas.TryGetValue(scopeId, out var areaName)
|
||||
? [UnsPath([areaName])]
|
||||
: [];
|
||||
|
||||
case NodeAclScopeKind.UnsLine:
|
||||
return TryUnsLineSegments(scopeId) is { } lineSegs ? [UnsPath(lineSegs)] : [];
|
||||
|
||||
case NodeAclScopeKind.Equipment:
|
||||
return TryEquipmentSegments(scopeId) is { } eqSegs ? [UnsPath(eqSegs)] : [];
|
||||
|
||||
case NodeAclScopeKind.Tag:
|
||||
return ResolveTag(scopeId);
|
||||
|
||||
case NodeAclScopeKind.RawFolder:
|
||||
return TryFolderChain(scopeId) is { } folderSegs ? [RawPath(folderSegs)] : [];
|
||||
|
||||
case NodeAclScopeKind.RawDriver:
|
||||
return TryDriverSegments(scopeId) is { } driverSegs ? [RawPath(driverSegs)] : [];
|
||||
|
||||
case NodeAclScopeKind.RawDevice:
|
||||
return TryDeviceSegments(scopeId) is { } deviceSegs ? [RawPath(deviceSegs)] : [];
|
||||
|
||||
case NodeAclScopeKind.RawTagGroup:
|
||||
return TryGroupSegments(scopeId) is { } groupSegs ? [RawPath(groupSegs)] : [];
|
||||
|
||||
// Cluster never reaches here (the caller short-circuits it), and FolderSegment is the retired
|
||||
// v2 kind with no v3 entity behind it — deliberately unresolvable, so an operator who still
|
||||
// has such a row gets a diagnostic naming it rather than a grant that quietly does nothing.
|
||||
case NodeAclScopeKind.Cluster:
|
||||
case NodeAclScopeKind.FolderSegment:
|
||||
default:
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
private IReadOnlyList<NodeAclPath> ResolveTag(string tagId)
|
||||
{
|
||||
var paths = new List<NodeAclPath>();
|
||||
|
||||
if (_tags.TryGetValue(tagId, out var tag))
|
||||
{
|
||||
var rawPath = _rawPaths.TryBuildTagPath(tag.DeviceId, tag.TagGroupId, tag.Name);
|
||||
if (rawPath is not null)
|
||||
paths.Add(RawPath(rawPath.Split(RawPaths.Separator)));
|
||||
}
|
||||
|
||||
// Every UNS projection of this raw tag. A tag referenced by three equipments is reachable at four
|
||||
// NodeIds, and a write through any of them lands on the same driver reference — so a Tag-scoped
|
||||
// grant has to cover all four or it is bypassable through whichever one it missed.
|
||||
foreach (var reference in _references)
|
||||
{
|
||||
if (!string.Equals(reference.TagId, tagId, StringComparison.Ordinal)) continue;
|
||||
if (TryEquipmentSegments(reference.EquipmentId) is not { } equipSegs) continue;
|
||||
paths.Add(UnsPath([.. equipSegs, reference.EffectiveName]));
|
||||
}
|
||||
|
||||
return paths;
|
||||
}
|
||||
|
||||
private string[]? TryUnsLineSegments(string lineId)
|
||||
{
|
||||
if (!_lines.TryGetValue(lineId, out var line)) return null;
|
||||
if (!_areas.TryGetValue(line.UnsAreaId, out var areaName)) return null;
|
||||
return [areaName, line.Name];
|
||||
}
|
||||
|
||||
private string[]? TryEquipmentSegments(string equipmentId)
|
||||
{
|
||||
if (!_equipment.TryGetValue(equipmentId, out var equip)) return null;
|
||||
if (TryUnsLineSegments(equip.UnsLineId) is not { } lineSegs) return null;
|
||||
return [.. lineSegs, equip.Name];
|
||||
}
|
||||
|
||||
private string[]? TryFolderChain(string? leafFolderId)
|
||||
{
|
||||
if (leafFolderId is null) return [];
|
||||
|
||||
var chain = new List<string>();
|
||||
var current = leafFolderId;
|
||||
var guard = 0;
|
||||
|
||||
// Depth-bounded like RawPathResolver's own walks: this is a corrupt-parent-cycle guard, not a
|
||||
// schema limit — raw folder nesting is unbounded by design.
|
||||
while (current is not null)
|
||||
{
|
||||
if (++guard > MaxAncestryDepth) return null;
|
||||
if (!_folders.TryGetValue(current, out var folder)) return null;
|
||||
chain.Add(folder.Name);
|
||||
current = folder.ParentId;
|
||||
}
|
||||
|
||||
chain.Reverse();
|
||||
return [.. chain];
|
||||
}
|
||||
|
||||
private string[]? TryDriverSegments(string driverInstanceId)
|
||||
{
|
||||
if (!_drivers.TryGetValue(driverInstanceId, out var driver)) return null;
|
||||
if (TryFolderChain(driver.RawFolderId) is not { } folderSegs) return null;
|
||||
return [.. folderSegs, driver.Name];
|
||||
}
|
||||
|
||||
private string[]? TryDeviceSegments(string deviceId)
|
||||
{
|
||||
if (!_devices.TryGetValue(deviceId, out var device)) return null;
|
||||
if (TryDriverSegments(device.DriverInstanceId) is not { } driverSegs) return null;
|
||||
return [.. driverSegs, device.Name];
|
||||
}
|
||||
|
||||
private string[]? TryGroupSegments(string tagGroupId)
|
||||
{
|
||||
if (!_groups.TryGetValue(tagGroupId, out var group)) return null;
|
||||
if (TryDeviceSegments(group.DeviceId) is not { } deviceSegs) return null;
|
||||
|
||||
var chain = new List<string>();
|
||||
string? current = tagGroupId;
|
||||
var guard = 0;
|
||||
|
||||
while (current is not null)
|
||||
{
|
||||
if (++guard > MaxAncestryDepth) return null;
|
||||
if (!_groups.TryGetValue(current, out var node)) return null;
|
||||
chain.Add(node.Name);
|
||||
current = node.ParentId;
|
||||
}
|
||||
|
||||
chain.Reverse();
|
||||
return [.. deviceSegs, .. chain];
|
||||
}
|
||||
|
||||
// No params-array overloads here: string[] binds to both params and IEnumerable, and the resulting
|
||||
// ambiguity would be resolved silently by overload rules rather than by intent.
|
||||
private static NodeAclPath RawPath(IEnumerable<string> segments) =>
|
||||
new([NodeAclRealms.Raw, .. segments]);
|
||||
|
||||
private static NodeAclPath UnsPath(IEnumerable<string> segments) =>
|
||||
new([NodeAclRealms.Uns, .. segments]);
|
||||
|
||||
private const int MaxAncestryDepth = 256;
|
||||
}
|
||||
@@ -22,7 +22,8 @@ namespace ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
public sealed class DataPlaneAuthoritySnapshot
|
||||
{
|
||||
/// <summary>The state of a node that has not yet applied an artifact. Authenticates nothing.</summary>
|
||||
public static readonly DataPlaneAuthoritySnapshot Empty = Create(null, string.Empty, 0, [], []);
|
||||
public static readonly DataPlaneAuthoritySnapshot Empty =
|
||||
Create(null, string.Empty, 0, [], [], new Dictionary<AclScopeRef, IReadOnlyList<NodeAclPath>>());
|
||||
|
||||
private DataPlaneAuthoritySnapshot(
|
||||
string? clusterId,
|
||||
@@ -30,6 +31,7 @@ public sealed class DataPlaneAuthoritySnapshot
|
||||
long generationId,
|
||||
IReadOnlyList<ApiKey> keys,
|
||||
IReadOnlyList<NodeAcl> grants,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths,
|
||||
IReadOnlyDictionary<string, ApiKey> keysById,
|
||||
IReadOnlyDictionary<string, IReadOnlyList<NodeAcl>> grantsByPrincipal)
|
||||
{
|
||||
@@ -38,6 +40,7 @@ public sealed class DataPlaneAuthoritySnapshot
|
||||
GenerationId = generationId;
|
||||
Keys = keys;
|
||||
Grants = grants;
|
||||
ScopePaths = scopePaths;
|
||||
_keysById = keysById;
|
||||
_grantsByPrincipal = grantsByPrincipal;
|
||||
}
|
||||
@@ -66,6 +69,13 @@ public sealed class DataPlaneAuthoritySnapshot
|
||||
/// <summary>Every ACL grant scoped to this node's cluster.</summary>
|
||||
public IReadOnlyList<NodeAcl> Grants { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Where each grant's scope sits in the address space, resolved from the same artifact the grants
|
||||
/// came from. Feeds <see cref="PermissionTrieBuilder.Build"/>; a scope absent here has no
|
||||
/// deployed node and its grant is dropped rather than planted somewhere unreachable.
|
||||
/// </summary>
|
||||
public IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> ScopePaths { get; }
|
||||
|
||||
/// <summary>True once a real artifact has been applied.</summary>
|
||||
public bool HasArtifact => GenerationId > 0;
|
||||
|
||||
@@ -101,17 +111,20 @@ public sealed class DataPlaneAuthoritySnapshot
|
||||
/// <param name="generationId">The node-local generation stamp.</param>
|
||||
/// <param name="keys">The API keys carried by the artifact.</param>
|
||||
/// <param name="grants">The ACL grants for this node's cluster.</param>
|
||||
/// <param name="scopePaths">Where each grant's scope sits in the address space.</param>
|
||||
/// <returns>The built snapshot.</returns>
|
||||
public static DataPlaneAuthoritySnapshot Create(
|
||||
string? clusterId,
|
||||
string revisionHash,
|
||||
long generationId,
|
||||
IReadOnlyList<ApiKey> keys,
|
||||
IReadOnlyList<NodeAcl> grants)
|
||||
IReadOnlyList<NodeAcl> grants,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(revisionHash);
|
||||
ArgumentNullException.ThrowIfNull(keys);
|
||||
ArgumentNullException.ThrowIfNull(grants);
|
||||
ArgumentNullException.ThrowIfNull(scopePaths);
|
||||
|
||||
// OrdinalIgnoreCase throughout: key ids are minted as lowercase hex, but a client hand-copying a
|
||||
// key out of the AdminUI can upper-case it, and the principal comparison must agree with the
|
||||
@@ -140,7 +153,8 @@ public sealed class DataPlaneAuthoritySnapshot
|
||||
kv => (IReadOnlyList<NodeAcl>)kv.Value,
|
||||
StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
return new DataPlaneAuthoritySnapshot(clusterId, revisionHash, generationId, keys, grants, byId, frozen);
|
||||
return new DataPlaneAuthoritySnapshot(
|
||||
clusterId, revisionHash, generationId, keys, grants, scopePaths, byId, frozen);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -179,12 +193,14 @@ public interface IDataPlaneAuthoritySink
|
||||
/// <param name="revisionHash">SHA-256 of the artifact bytes.</param>
|
||||
/// <param name="keys">The API keys the artifact carries.</param>
|
||||
/// <param name="grants">The ACL grants for this node's cluster.</param>
|
||||
/// <param name="scopePaths">Where each grant's scope sits in the address space.</param>
|
||||
/// <returns>The installed snapshot.</returns>
|
||||
DataPlaneAuthoritySnapshot Apply(
|
||||
string? clusterId,
|
||||
string revisionHash,
|
||||
IReadOnlyList<ApiKey> keys,
|
||||
IReadOnlyList<NodeAcl> grants);
|
||||
IReadOnlyList<NodeAcl> grants,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -204,7 +220,8 @@ public sealed class DataPlaneAuthorityState : IDataPlaneAuthoritySource, IDataPl
|
||||
string? clusterId,
|
||||
string revisionHash,
|
||||
IReadOnlyList<ApiKey> keys,
|
||||
IReadOnlyList<NodeAcl> grants)
|
||||
IReadOnlyList<NodeAcl> grants,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(revisionHash);
|
||||
|
||||
@@ -227,7 +244,8 @@ public sealed class DataPlaneAuthorityState : IDataPlaneAuthoritySource, IDataPl
|
||||
? previous.GenerationId
|
||||
: previous.GenerationId + 1;
|
||||
|
||||
var next = DataPlaneAuthoritySnapshot.Create(clusterId, revisionHash, generation, keys, grants);
|
||||
var next = DataPlaneAuthoritySnapshot.Create(
|
||||
clusterId, revisionHash, generation, keys, grants, scopePaths);
|
||||
Volatile.Write(ref _current, next);
|
||||
return next;
|
||||
}
|
||||
|
||||
@@ -1,47 +1,146 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
|
||||
/// <summary>
|
||||
/// Address of a node in the 6-level scope hierarchy the Phase 6.2 evaluator walks.
|
||||
/// Assembled by the dispatch layer from the node's namespace + UNS path + tag; passed
|
||||
/// to <see cref="IPermissionEvaluator"/> which walks the matching trie path.
|
||||
/// Address of a node in the ACL scope hierarchy the evaluator walks: a cluster, a realm, and the
|
||||
/// node's path within that realm. Assembled by the dispatch layer from the node's NodeId; passed to
|
||||
/// <see cref="IPermissionEvaluator"/>, which walks the matching trie path.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>Per the Phase 6.2 Stream B plan the hierarchy is
|
||||
/// <c>Cluster → Namespace → UnsArea → UnsLine → Equipment → Tag</c> for all
|
||||
/// (Equipment-kind) namespaces. Galaxy is a standard Equipment-kind driver, so Galaxy
|
||||
/// points are ordinary equipment tags that resolve through this same walk.</para>
|
||||
///
|
||||
/// <para>Unset mid-path levels (e.g. a Cluster-scoped request with no UnsArea) leave
|
||||
/// the corresponding id <c>null</c>. The evaluator walks as far as the scope goes +
|
||||
/// stops at the first null.</para>
|
||||
/// <para>
|
||||
/// The hierarchy is <c>Cluster → Realm → …node path…</c>. The node path is <b>variable length</b>,
|
||||
/// which is the whole reason this type is no longer a fixed set of level properties (#520 stage 3):
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item>
|
||||
/// <b>UNS</b> paths are always <c>Area / Line / Equipment [/ EffectiveName]</c> — fixed depth,
|
||||
/// because equipment is a tree leaf.
|
||||
/// </item>
|
||||
/// <item>
|
||||
/// <b>Raw</b> paths are <c>folder… / Driver / Device / group… / Tag</c>, and BOTH the folder
|
||||
/// chain and the tag-group chain nest arbitrarily deep (<c>RawFolder.ParentRawFolderId</c>,
|
||||
/// <c>TagGroup.ParentTagGroupId</c>). There is no schema depth cap — the 256 in
|
||||
/// <c>RawPathResolver</c> is a corrupt-cycle guard, not a limit. A fixed-arity scope record
|
||||
/// therefore cannot address a real raw tree at all; the previous six-property shape silently
|
||||
/// capped it at five levels and mislabelled every one of them.
|
||||
/// </item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// The realm segment is NOT carried here. It is derived from <see cref="Kind"/> by
|
||||
/// <see cref="NodeAclRealms.SegmentFor(NodeHierarchyKind)"/>, which the scope-path producer also uses — so the two
|
||||
/// sides cannot disagree about its spelling. That matters more than it looks: the realm is a hard
|
||||
/// gate at level 1 of the walk, so a mismatch would make every sub-cluster grant in the system
|
||||
/// unreachable while cluster-scoped grants kept working, which reads as "ACLs work" right up until
|
||||
/// someone tries to narrow one.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed record NodeScope
|
||||
{
|
||||
/// <summary>Cluster the node belongs to. Required.</summary>
|
||||
public required string ClusterId { get; init; }
|
||||
|
||||
/// <summary>Namespace within the cluster. Null is not allowed for a request against a real node.</summary>
|
||||
public string? NamespaceId { get; init; }
|
||||
|
||||
/// <summary>UNS area (e.g. "warsaw-west") below the namespace.</summary>
|
||||
public string? UnsAreaId { get; init; }
|
||||
|
||||
/// <summary>UNS line below the area.</summary>
|
||||
public string? UnsLineId { get; init; }
|
||||
|
||||
/// <summary>Equipment row below the line.</summary>
|
||||
public string? EquipmentId { get; init; }
|
||||
|
||||
/// <summary>Target tag id when the scope addresses a specific tag; null for equipment-level scopes.</summary>
|
||||
public string? TagId { get; init; }
|
||||
|
||||
/// <summary>Which hierarchy applies. Currently only Equipment-kind (UNS) exists.</summary>
|
||||
/// <summary>Which realm — and therefore which hierarchy shape — the node lives in.</summary>
|
||||
public required NodeHierarchyKind Kind { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// The node's path within its realm, root-first, excluding the realm segment itself. Empty
|
||||
/// addresses the realm as a whole. Segment comparison is case-sensitive ordinal, matching
|
||||
/// <c>RawPaths.Comparer</c> and OPC UA NodeId identity.
|
||||
/// </summary>
|
||||
public required IReadOnlyList<string> Segments { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>Selector for the scope-hierarchy shape.</summary>
|
||||
/// <summary>Selector for the scope-hierarchy shape — one member per OPC UA namespace (realm).</summary>
|
||||
public enum NodeHierarchyKind
|
||||
{
|
||||
/// <summary><c>Cluster → Namespace → UnsArea → UnsLine → Equipment → Tag</c> — UNS / Equipment kind.</summary>
|
||||
Equipment,
|
||||
/// <summary><c>Area / Line / Equipment [/ EffectiveName]</c> — the UNS realm.</summary>
|
||||
Uns,
|
||||
|
||||
/// <summary><c>folder… / Driver / Device / group… / Tag</c> — the raw device-tree realm. (Appended, #520 stage 3.)</summary>
|
||||
Raw,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The single authority for the realm segment that sits at level 1 of every permission trie, directly
|
||||
/// under the cluster root.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This exists because v3 <b>has no <c>Namespace</c> entity</b>. The snapshot was retired when the
|
||||
/// address space went dual-namespace ("the two OPC UA namespaces are implicit"), which left the
|
||||
/// trie's level-1 gate with no configured key source at all — the pre-stage-3 walker read a
|
||||
/// <c>NamespaceId</c> that nothing in the system ever produced, so the level could only ever fail
|
||||
/// to match. Deriving the segment from the realm restores the level as something real without
|
||||
/// reintroducing an entity.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The short tokens, rather than the namespace URIs, are deliberate: they are what an operator
|
||||
/// types into a <see cref="Configuration.Enums.NodeAclScopeKind.Namespace"/> row's <c>ScopeId</c>,
|
||||
/// and they read clearly in a diagnostic. They cannot collide with a user-authored segment,
|
||||
/// because only a realm token is ever placed at level 1 — real names start at level 2.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class NodeAclRealms
|
||||
{
|
||||
/// <summary>Realm segment for the raw device tree (<c>https://zb.com/otopcua/raw</c>).</summary>
|
||||
public const string Raw = "raw";
|
||||
|
||||
/// <summary>Realm segment for the UNS tree (<c>https://zb.com/otopcua/uns</c>).</summary>
|
||||
public const string Uns = "uns";
|
||||
|
||||
/// <summary>The realm segment for a hierarchy kind.</summary>
|
||||
/// <param name="kind">The hierarchy kind.</param>
|
||||
/// <returns>The level-1 trie segment.</returns>
|
||||
/// <exception cref="ArgumentOutOfRangeException">The kind is not a defined member.</exception>
|
||||
public static string SegmentFor(NodeHierarchyKind kind) => kind switch
|
||||
{
|
||||
NodeHierarchyKind.Uns => Uns,
|
||||
NodeHierarchyKind.Raw => Raw,
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "Unhandled hierarchy kind."),
|
||||
};
|
||||
|
||||
/// <summary>The realm segment for an address-space realm.</summary>
|
||||
/// <param name="realm">The address-space realm carried at the OPC UA sinks.</param>
|
||||
/// <returns>The level-1 trie segment.</returns>
|
||||
/// <exception cref="ArgumentOutOfRangeException">The realm is not a defined member.</exception>
|
||||
public static string SegmentFor(AddressSpaceRealm realm) => realm switch
|
||||
{
|
||||
AddressSpaceRealm.Uns => Uns,
|
||||
AddressSpaceRealm.Raw => Raw,
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(realm), realm, "Unhandled address-space realm."),
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// True when <paramref name="segment"/> is exactly a canonical realm segment. Used by the trie
|
||||
/// builder to reject a scope path that does not start at a realm — such a path addresses a node
|
||||
/// the walk cannot reach, so the grant would look planted and never match.
|
||||
/// </summary>
|
||||
/// <param name="segment">The candidate segment.</param>
|
||||
/// <returns><see langword="true"/> when it is a realm segment.</returns>
|
||||
public static bool IsRealmSegment(string? segment) =>
|
||||
string.Equals(segment, Raw, StringComparison.Ordinal)
|
||||
|| string.Equals(segment, Uns, StringComparison.Ordinal);
|
||||
|
||||
/// <summary>
|
||||
/// Canonicalizes an operator-supplied realm token from a <c>Namespace</c>-scoped row's
|
||||
/// <c>ScopeId</c>. Accepts the short token or the full namespace URI, in any case.
|
||||
/// </summary>
|
||||
/// <param name="scopeId">The authored scope id.</param>
|
||||
/// <returns>The canonical realm segment, or <see langword="null"/> when it names no realm.</returns>
|
||||
public static string? TryCanonicalize(string? scopeId)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(scopeId)) return null;
|
||||
var trimmed = scopeId.Trim();
|
||||
|
||||
if (string.Equals(trimmed, Raw, StringComparison.OrdinalIgnoreCase)
|
||||
|| string.Equals(trimmed, V3NodeIds.RawNamespaceUri, StringComparison.OrdinalIgnoreCase))
|
||||
return Raw;
|
||||
|
||||
if (string.Equals(trimmed, Uns, StringComparison.OrdinalIgnoreCase)
|
||||
|| string.Equals(trimmed, V3NodeIds.UnsNamespaceUri, StringComparison.OrdinalIgnoreCase))
|
||||
return Uns;
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,17 +3,16 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
|
||||
/// <summary>
|
||||
/// In-memory permission trie for one <c>(ClusterId, GenerationId)</c>. Walk from the cluster
|
||||
/// root down through namespace → UNS levels → tag, OR-ing the
|
||||
/// In-memory permission trie for one <c>(ClusterId, GenerationId)</c>. Walk from the cluster root
|
||||
/// down through the realm and then each segment of the node's path, OR-ing the
|
||||
/// <see cref="TrieGrant.PermissionFlags"/> granted at each visited level for each of the session's
|
||||
/// principals. The accumulated bitmask is compared to the permission required by the
|
||||
/// requested <see cref="Abstractions.OpcUaOperation"/>.
|
||||
/// principals. The accumulated bitmask is compared to the permission required by the requested
|
||||
/// <see cref="Abstractions.OpcUaOperation"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The walk is pure union (additive grants; no explicit Deny in v2.0):
|
||||
/// encountering a grant at any level contributes its flags, never revokes them. A grant at
|
||||
/// the Cluster root therefore cascades to every tag below it; a grant at a deep equipment
|
||||
/// leaf is visible only on that equipment subtree.
|
||||
/// The walk is pure union (additive grants; no explicit Deny in v2.0): encountering a grant at any
|
||||
/// level contributes its flags, never revokes them. A grant at the cluster root therefore cascades to
|
||||
/// every node below it; a grant at a deep leaf is visible only on that subtree.
|
||||
/// </remarks>
|
||||
public sealed class PermissionTrie
|
||||
{
|
||||
@@ -27,9 +26,9 @@ public sealed class PermissionTrie
|
||||
public PermissionTrieNode Root { get; init; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// Walk the trie collecting grants that apply to <paramref name="scope"/> for any of the
|
||||
/// session's <paramref name="principals"/>. Returns the matched-grant list; the caller
|
||||
/// OR-s the flag bits to decide whether the requested permission is carried.
|
||||
/// Walk the trie collecting grants that apply to <paramref name="scope"/> for any of the session's
|
||||
/// <paramref name="principals"/>. Returns the matched-grant list; the caller OR-s the flag bits to
|
||||
/// decide whether the requested permission is carried.
|
||||
/// </summary>
|
||||
/// <param name="scope">The node scope to match permissions for.</param>
|
||||
/// <param name="principals">The principal names carried by the session (API-key principals, or the reserved "anonymous").</param>
|
||||
@@ -44,47 +43,42 @@ public sealed class PermissionTrie
|
||||
|
||||
var matches = new List<MatchedGrant>();
|
||||
|
||||
// Level 0 — cluster-scoped grants.
|
||||
CollectAtLevel(Root, NodeAclScopeKind.Cluster, groups, matches);
|
||||
// Level 0 — cluster-scoped grants apply to every node in the cluster.
|
||||
CollectAtLevel(Root, groups, matches);
|
||||
|
||||
// Level 1 — namespace.
|
||||
if (scope.NamespaceId is null) return matches;
|
||||
if (!Root.Children.TryGetValue(scope.NamespaceId, out var ns)) return matches;
|
||||
CollectAtLevel(ns, NodeAclScopeKind.Namespace, groups, matches);
|
||||
// Level 1 — the realm. Derived from the scope's kind rather than carried on it, so this can
|
||||
// never disagree with the spelling the scope-path producer used. SegmentFor throws on an
|
||||
// undefined kind, which is deliberate: a new realm that nobody taught this walk about must fail
|
||||
// loudly rather than walk some other realm's subtree and return a confidently wrong verdict.
|
||||
var realm = NodeAclRealms.SegmentFor(scope.Kind);
|
||||
if (!Root.Children.TryGetValue(realm, out var node)) return matches;
|
||||
CollectAtLevel(node, groups, matches);
|
||||
|
||||
// Below the namespace every kind walks the Equipment hierarchy — Galaxy is a standard
|
||||
// Equipment-kind driver, so Galaxy points are ordinary equipment tags keyed by
|
||||
// EquipmentId/path and resolve through this same walk.
|
||||
WalkEquipment(ns, scope, groups, matches);
|
||||
// Levels 2..n — the node's path within the realm, however deep it happens to be. There is no
|
||||
// per-kind ladder here on purpose: the UNS path (Area/Line/Equipment) and a raw path
|
||||
// (folder…/Driver/Device/group…/Tag) are both just ordered segments, and raw nesting is
|
||||
// unbounded, so any fixed ladder would silently truncate deep raw trees.
|
||||
foreach (var segment in scope.Segments)
|
||||
{
|
||||
if (segment is null || !node.Children.TryGetValue(segment, out var next)) return matches;
|
||||
node = next;
|
||||
CollectAtLevel(node, groups, matches);
|
||||
}
|
||||
|
||||
return matches;
|
||||
}
|
||||
|
||||
private static void WalkEquipment(PermissionTrieNode ns, NodeScope scope, HashSet<string> groups, List<MatchedGrant> matches)
|
||||
{
|
||||
if (scope.UnsAreaId is null) return;
|
||||
if (!ns.Children.TryGetValue(scope.UnsAreaId, out var area)) return;
|
||||
CollectAtLevel(area, NodeAclScopeKind.UnsArea, groups, matches);
|
||||
|
||||
if (scope.UnsLineId is null) return;
|
||||
if (!area.Children.TryGetValue(scope.UnsLineId, out var line)) return;
|
||||
CollectAtLevel(line, NodeAclScopeKind.UnsLine, groups, matches);
|
||||
|
||||
if (scope.EquipmentId is null) return;
|
||||
if (!line.Children.TryGetValue(scope.EquipmentId, out var eq)) return;
|
||||
CollectAtLevel(eq, NodeAclScopeKind.Equipment, groups, matches);
|
||||
|
||||
if (scope.TagId is null) return;
|
||||
if (!eq.Children.TryGetValue(scope.TagId, out var tag)) return;
|
||||
CollectAtLevel(tag, NodeAclScopeKind.Tag, groups, matches);
|
||||
}
|
||||
|
||||
private static void CollectAtLevel(PermissionTrieNode node, NodeAclScopeKind level, HashSet<string> groups, List<MatchedGrant> matches)
|
||||
private static void CollectAtLevel(PermissionTrieNode node, HashSet<string> groups, List<MatchedGrant> matches)
|
||||
{
|
||||
foreach (var grant in node.Grants)
|
||||
{
|
||||
// Provenance is the granting ROW's own scope kind, recorded when the trie was built — not the
|
||||
// structural depth the grant happens to sit at. Depth-derived provenance was wrong in two
|
||||
// directions: it could not name a raw level at all (the depth of "Device" varies with folder
|
||||
// nesting), and where a producer emitted a path whose length disagreed with the row's kind it
|
||||
// reported a level the operator never authored.
|
||||
if (groups.Contains(grant.Principal))
|
||||
matches.Add(new MatchedGrant(grant.Principal, level, grant.PermissionFlags));
|
||||
matches.Add(new MatchedGrant(grant.Principal, grant.ScopeKind, grant.PermissionFlags));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -96,12 +90,21 @@ public sealed class PermissionTrieNode
|
||||
public List<TrieGrant> Grants { get; } = [];
|
||||
|
||||
/// <summary>
|
||||
/// Children keyed by the next level's id — namespace id under cluster; UnsAreaId or
|
||||
/// folder-segment name under namespace; etc. Comparer is OrdinalIgnoreCase so the walk
|
||||
/// tolerates case drift between the NodeAcl row and the requested scope.
|
||||
/// Children keyed by the next level's segment — the realm token under the root, then entity names.
|
||||
/// </summary>
|
||||
public Dictionary<string, PermissionTrieNode> Children { get; } = new(StringComparer.OrdinalIgnoreCase);
|
||||
/// <remarks>
|
||||
/// ⚠️ The comparer is <b>case-sensitive ordinal</b>, matching <c>RawPaths.Comparer</c> and OPC UA
|
||||
/// NodeId identity. It was <c>OrdinalIgnoreCase</c> before #520 stage 3, which was a silent
|
||||
/// widening: raw sibling names are unique under an ordinal comparer, so <c>Speed</c> and
|
||||
/// <c>speed</c> can both exist under one device, and a grant on either would have matched both.
|
||||
/// Case-sensitive matching is also the fail-closed direction — a case-drifted ACL row now grants
|
||||
/// nothing instead of granting something adjacent.
|
||||
/// </remarks>
|
||||
public Dictionary<string, PermissionTrieNode> Children { get; } = new(StringComparer.Ordinal);
|
||||
}
|
||||
|
||||
/// <summary>Projection of a <see cref="Configuration.Entities.NodeAcl"/> row into the trie.</summary>
|
||||
public sealed record TrieGrant(string Principal, NodePermissions PermissionFlags);
|
||||
/// <param name="Principal">The principal the row grants to.</param>
|
||||
/// <param name="ScopeKind">The row's authored scope kind, carried for decision provenance.</param>
|
||||
/// <param name="PermissionFlags">The permission bits the row grants.</param>
|
||||
public sealed record TrieGrant(string Principal, NodeAclScopeKind ScopeKind, NodePermissions PermissionFlags);
|
||||
|
||||
@@ -4,107 +4,116 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
namespace ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
|
||||
/// <summary>
|
||||
/// Builds a <see cref="PermissionTrie"/> from a set of <see cref="NodeAcl"/> rows anchored
|
||||
/// in one generation. The trie is keyed on the rows' scope hierarchy — rows with
|
||||
/// <see cref="NodeAclScopeKind.Cluster"/> land at the trie root, rows with
|
||||
/// <see cref="NodeAclScopeKind.Tag"/> land at a leaf, etc.
|
||||
/// Builds a <see cref="PermissionTrie"/> from a set of <see cref="NodeAcl"/> rows anchored in one
|
||||
/// generation. Rows with <see cref="NodeAclScopeKind.Cluster"/> land at the trie root; every other
|
||||
/// row is placed at the trie node(s) its <c>ScopeId</c> resolves to.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>Intended to be called by <see cref="PermissionTrieCache"/> once per published
|
||||
/// generation; the resulting trie is immutable for the life of the cache entry. Idempotent —
|
||||
/// two builds from the same rows produce equal tries (grant lists may be in insertion order;
|
||||
/// evaluators don't depend on order).</para>
|
||||
///
|
||||
/// <para>The builder deliberately does not know about the node-row metadata the trie path
|
||||
/// will be walked with. The caller assembles <see cref="NodeScope"/> values from the live
|
||||
/// config (UnsArea parent of UnsLine, etc.); this class only honors the <c>ScopeId</c>
|
||||
/// each row carries.</para>
|
||||
/// <para>
|
||||
/// Intended to be called once per published generation; the resulting trie is immutable for the
|
||||
/// life of the cache entry. Idempotent — two builds from the same rows produce equal tries.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// ⚠️ <b>There is no longer a "deterministic test mode".</b> Before #520 stage 3 a null
|
||||
/// <c>scopePaths</c> made sub-cluster rows fall back to a direct child of the trie
|
||||
/// root keyed on <c>ScopeId</c>. That position is unreachable by construction — level 1 of the walk
|
||||
/// is the realm — so the fallback produced grants that looked placed and could never match, and
|
||||
/// every test that used it proved nothing about production placement. A row that cannot be
|
||||
/// resolved is now <b>dropped with a diagnostic</b>, which is the fail-closed direction and is
|
||||
/// honest about what happened.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class PermissionTrieBuilder
|
||||
{
|
||||
/// <summary>
|
||||
/// Build a trie for one cluster/generation from the supplied rows. The caller is
|
||||
/// responsible for pre-filtering rows to the target generation + cluster.
|
||||
/// Build a trie for one cluster/generation from the supplied rows. The caller is responsible for
|
||||
/// pre-filtering rows to the target generation + cluster.
|
||||
/// </summary>
|
||||
/// <param name="clusterId">Cluster the trie is being built for; rows for other clusters are skipped.</param>
|
||||
/// <param name="generationId">Config-generation the rows belong to; stamped on the returned trie.</param>
|
||||
/// <param name="rows">ACL rows for this cluster + generation.</param>
|
||||
/// <param name="scopePaths">
|
||||
/// Optional <c>ScopeId</c> → multi-level trie-path lookup. When supplied, sub-cluster rows
|
||||
/// descend to their structurally-correct trie node. When null, sub-cluster rows fall back
|
||||
/// to a direct child of the trie root keyed on <c>ScopeId</c> — deterministic-test mode.
|
||||
/// <c>(ScopeKind, ScopeId)</c> → the trie path(s) that scope resolves to, as produced by
|
||||
/// <see cref="AclScopePathResolver" />. A scope resolves to <b>several</b> paths when one entity is
|
||||
/// reachable at several places in the address space — a raw tag projected into N equipments by
|
||||
/// <c>UnsTagReference</c> rows has one raw path plus N UNS paths, and a grant on it must cover all
|
||||
/// of them or it would be bypassable through the NodeId it missed.
|
||||
/// </param>
|
||||
/// <param name="diagnostic">
|
||||
/// Optional callback invoked when a sub-cluster row's <c>ScopeId</c> cannot be located
|
||||
/// in <paramref name="scopePaths"/>. Production callers should wire a logger here so
|
||||
/// orphaned grants surface — silently dropping them under the wrong trie level was a
|
||||
/// production hazard. The callback fires only when <paramref name="scopePaths"/>
|
||||
/// is non-null (a null lookup is the explicit deterministic-test fallback mode).
|
||||
/// Optional callback invoked for every row that could not be placed. Production callers should wire
|
||||
/// a logger here — a dropped grant is invisible otherwise.
|
||||
/// </param>
|
||||
/// <returns>The built <see cref="PermissionTrie"/> for the cluster + generation.</returns>
|
||||
public static PermissionTrie Build(
|
||||
string clusterId,
|
||||
long generationId,
|
||||
IReadOnlyList<NodeAcl> rows,
|
||||
IReadOnlyDictionary<string, NodeAclPath>? scopePaths = null,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> scopePaths,
|
||||
Action<PermissionTrieBuildDiagnostic>? diagnostic = null)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(clusterId);
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
ArgumentNullException.ThrowIfNull(scopePaths);
|
||||
|
||||
var trie = new PermissionTrie { ClusterId = clusterId, GenerationId = generationId };
|
||||
|
||||
foreach (var row in rows)
|
||||
{
|
||||
if (!string.Equals(row.ClusterId, clusterId, StringComparison.OrdinalIgnoreCase)) continue;
|
||||
var grant = new TrieGrant(row.Principal, row.PermissionFlags);
|
||||
|
||||
var node = row.ScopeKind switch
|
||||
var grant = new TrieGrant(row.Principal, row.ScopeKind, row.PermissionFlags);
|
||||
|
||||
if (row.ScopeKind == NodeAclScopeKind.Cluster)
|
||||
{
|
||||
NodeAclScopeKind.Cluster => trie.Root,
|
||||
_ => Descend(trie.Root, row, scopePaths, diagnostic),
|
||||
};
|
||||
trie.Root.Grants.Add(grant);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (node is not null)
|
||||
// A sub-cluster row with no ScopeId names nothing. It used to vanish here with no signal at
|
||||
// all — unlike an unresolvable ScopeId, which at least emitted a diagnostic. Both are
|
||||
// authoring mistakes and both now say so.
|
||||
if (string.IsNullOrEmpty(row.ScopeId))
|
||||
{
|
||||
diagnostic?.Invoke(new PermissionTrieBuildDiagnostic(
|
||||
row.NodeAclId, row.ScopeKind, ScopeId: null,
|
||||
PermissionTrieBuildDiagnosticReason.MissingScopeId));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!scopePaths.TryGetValue(new AclScopeRef(row.ScopeKind, row.ScopeId), out var paths)
|
||||
|| paths.Count == 0)
|
||||
{
|
||||
diagnostic?.Invoke(new PermissionTrieBuildDiagnostic(
|
||||
row.NodeAclId, row.ScopeKind, row.ScopeId,
|
||||
PermissionTrieBuildDiagnosticReason.UnresolvedScope));
|
||||
continue;
|
||||
}
|
||||
|
||||
foreach (var path in paths)
|
||||
{
|
||||
// Guard the producer's output contract. Level 1 of the walk is always a realm token, so a
|
||||
// path that is empty or does not start with one addresses a node the walker can never
|
||||
// reach — the grant would look planted and could never match. That is the same silent
|
||||
// failure the deleted root-child fallback used to produce; without this check it simply
|
||||
// moves into the resolver, where nothing else cross-checks it.
|
||||
if (path.Segments.Count == 0 || !NodeAclRealms.IsRealmSegment(path.Segments[0]))
|
||||
{
|
||||
diagnostic?.Invoke(new PermissionTrieBuildDiagnostic(
|
||||
row.NodeAclId, row.ScopeKind, row.ScopeId,
|
||||
PermissionTrieBuildDiagnosticReason.InvalidScopePath));
|
||||
continue;
|
||||
}
|
||||
|
||||
var node = trie.Root;
|
||||
foreach (var segment in path.Segments)
|
||||
node = EnsureChild(node, segment);
|
||||
node.Grants.Add(grant);
|
||||
}
|
||||
}
|
||||
|
||||
return trie;
|
||||
}
|
||||
|
||||
private static PermissionTrieNode? Descend(
|
||||
PermissionTrieNode root,
|
||||
NodeAcl row,
|
||||
IReadOnlyDictionary<string, NodeAclPath>? scopePaths,
|
||||
Action<PermissionTrieBuildDiagnostic>? diagnostic)
|
||||
{
|
||||
if (string.IsNullOrEmpty(row.ScopeId)) return null;
|
||||
|
||||
// For sub-cluster scopes the caller supplies a path lookup so we know the containing
|
||||
// namespace / UnsArea / UnsLine ids. Without a path lookup we fall back to putting the
|
||||
// row directly under the root using its ScopeId — works for deterministic tests, not
|
||||
// for production where the hierarchy must be honored. If a scopePaths lookup IS
|
||||
// provided but is missing the row's ScopeId, surface a diagnostic so the caller can
|
||||
// log the orphan instead of silently dropping the grant under an unreachable node.
|
||||
if (scopePaths is null || !scopePaths.TryGetValue(row.ScopeId, out var path))
|
||||
{
|
||||
if (scopePaths is not null)
|
||||
{
|
||||
diagnostic?.Invoke(new PermissionTrieBuildDiagnostic(
|
||||
NodeAclId: row.NodeAclId,
|
||||
ScopeKind: row.ScopeKind,
|
||||
ScopeId: row.ScopeId,
|
||||
Reason: PermissionTrieBuildDiagnosticReason.MissingScopePath));
|
||||
}
|
||||
return EnsureChild(root, row.ScopeId);
|
||||
}
|
||||
|
||||
var node = root;
|
||||
foreach (var segment in path.Segments)
|
||||
node = EnsureChild(node, segment);
|
||||
return node;
|
||||
}
|
||||
|
||||
private static PermissionTrieNode EnsureChild(PermissionTrieNode parent, string key)
|
||||
{
|
||||
if (!parent.Children.TryGetValue(key, out var child))
|
||||
@@ -117,37 +126,41 @@ public static class PermissionTrieBuilder
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ordered list of trie-path segments from root to the target node. Supplied to
|
||||
/// <see cref="PermissionTrieBuilder.Build"/> so the builder knows where a
|
||||
/// <see cref="NodeAclScopeKind.UnsLine"/>-scoped row sits in the hierarchy.
|
||||
/// Ordered list of trie-path segments from the cluster root to the target node, <b>including</b> the
|
||||
/// realm segment at index 0 (see <see cref="NodeAclRealms"/>).
|
||||
/// </summary>
|
||||
/// <param name="Segments">
|
||||
/// Namespace id, then UnsAreaId / UnsLineId / EquipmentId / TagId as applicable.
|
||||
/// </param>
|
||||
/// <param name="Segments">Realm token, then the entity names that lead to the scoped node.</param>
|
||||
public sealed record NodeAclPath(IReadOnlyList<string> Segments);
|
||||
|
||||
/// <summary>
|
||||
/// Diagnostic emitted by <see cref="PermissionTrieBuilder.Build"/> when a row could not be
|
||||
/// placed at its structurally-correct trie node. Production callers should log these so
|
||||
/// orphaned grants surface instead of being silently dropped under an unreachable node.
|
||||
/// Diagnostic emitted by <see cref="PermissionTrieBuilder.Build"/> for a row that could not be placed.
|
||||
/// Production callers should log these so dropped grants surface to an operator.
|
||||
/// </summary>
|
||||
/// <param name="NodeAclId">The offending row's logical id.</param>
|
||||
/// <param name="ScopeKind">The row's <see cref="NodeAclScopeKind"/>.</param>
|
||||
/// <param name="ScopeId">The row's <c>ScopeId</c> that could not be located.</param>
|
||||
/// <param name="ScopeId">The row's <c>ScopeId</c>, or <see langword="null"/> when it had none.</param>
|
||||
/// <param name="Reason">Why the diagnostic fired.</param>
|
||||
public sealed record PermissionTrieBuildDiagnostic(
|
||||
string NodeAclId,
|
||||
NodeAclScopeKind ScopeKind,
|
||||
string ScopeId,
|
||||
string? ScopeId,
|
||||
PermissionTrieBuildDiagnosticReason Reason);
|
||||
|
||||
/// <summary>Reasons <see cref="PermissionTrieBuildDiagnostic"/> can be emitted.</summary>
|
||||
/// <summary>Reasons <see cref="PermissionTrieBuildDiagnostic"/> can be emitted. The grant is dropped in every case.</summary>
|
||||
public enum PermissionTrieBuildDiagnosticReason
|
||||
{
|
||||
/// <summary>
|
||||
/// The row's <c>ScopeId</c> was not present in the supplied <c>scopePaths</c> lookup.
|
||||
/// The grant is placed as a direct child of the trie root keyed on <c>ScopeId</c> — a
|
||||
/// position the production trie walker cannot reach for multi-level scopes.
|
||||
/// The row's <c>ScopeId</c> did not resolve to any node in the deployed address space — a dangling
|
||||
/// id, a deleted entity, or a scope kind with no v3 meaning (<see cref="NodeAclScopeKind.FolderSegment"/>).
|
||||
/// </summary>
|
||||
MissingScopePath,
|
||||
UnresolvedScope,
|
||||
|
||||
/// <summary>The row is narrower than <see cref="NodeAclScopeKind.Cluster"/> but carries no <c>ScopeId</c>.</summary>
|
||||
MissingScopeId,
|
||||
|
||||
/// <summary>
|
||||
/// A resolved path was empty or did not begin with a realm segment, so it addresses a trie node
|
||||
/// the walk cannot reach. This is a bug in the scope-path producer, not an authoring mistake.
|
||||
/// </summary>
|
||||
InvalidScopePath,
|
||||
}
|
||||
|
||||
@@ -29,15 +29,28 @@ else if (!IsNew && _existing is null)
|
||||
else
|
||||
{
|
||||
<div class="alert alert-warning" role="alert">
|
||||
<strong>This grant will not be enforced.</strong>
|
||||
It is saved and shipped in every deployment artifact, but the OPC UA server never evaluates
|
||||
ACL rows — the permission evaluator has no production call site. Nothing you set below will
|
||||
change what a client can read, write, browse or acknowledge.
|
||||
<strong>Only <span class="mono">Cluster</span> scope is enforced today.</strong>
|
||||
Saved with scope kind <span class="mono">Cluster</span>, this grant confers a server-wide role
|
||||
on its principal: <span class="mono">WriteOperate</span> → writing any tag value;
|
||||
<span class="mono">AlarmAcknowledge</span> → the Part 9 alarm methods
|
||||
(acknowledge / confirm / shelve). No other permission bit is evaluated yet.
|
||||
<br />
|
||||
Real access control today is fleet-wide LDAP-group → role mapping
|
||||
(<span class="mono">Security:Ldap:GroupToRole</span>):
|
||||
<span class="mono">WriteOperate</span> to write any tag,
|
||||
<span class="mono">AlarmAck</span> to acknowledge any alarm. Reads are ungated.
|
||||
Saved with any narrower scope (<span class="mono">Namespace</span>,
|
||||
<span class="mono">UnsArea</span>, <span class="mono">UnsLine</span>,
|
||||
<span class="mono">Equipment</span>, <span class="mono">Tag</span>,
|
||||
<span class="mono">Raw*</span>) it is stored and shipped in every deployment artifact but
|
||||
<strong>confers nothing</strong> until per-node enforcement lands. That under-granting is
|
||||
deliberate: honouring its flags while its <em>scope</em> cannot be honoured would turn
|
||||
"WriteOperate on one equipment" into server-wide write authority.
|
||||
<br />
|
||||
Read, Browse, Subscribe and HistoryRead are <strong>not</strong> gated for any admitted
|
||||
session, including anonymous.
|
||||
<br />
|
||||
<strong>Principal</strong> is an API-key principal — or the reserved
|
||||
<span class="mono">anonymous</span> principal — not an LDAP group: a client presents an OPC UA
|
||||
UserName token with username <span class="mono">apikey</span> and password
|
||||
<span class="mono">otua_<keyId>_<secret></span>. Mint keys on the
|
||||
<span class="mono">/apikeys</span> page; LDAP now covers AdminUI login only.
|
||||
See <span class="mono">docs/security.md</span>.
|
||||
</div>
|
||||
|
||||
@@ -54,7 +67,7 @@ else
|
||||
<div class="col-md-6 mb-3">
|
||||
<label class="form-label" for="grp">Principal</label>
|
||||
<InputText id="grp" @bind-Value="_form.Principal" class="form-control form-control-sm mono"
|
||||
placeholder="cn=Operators,ou=FleetAdmin,dc=zb,dc=local" />
|
||||
placeholder="scadabridge-dcl" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
@@ -66,14 +79,34 @@ else
|
||||
<option value="@NodeAclScopeKind.UnsArea">UnsArea</option>
|
||||
<option value="@NodeAclScopeKind.UnsLine">UnsLine</option>
|
||||
<option value="@NodeAclScopeKind.Equipment">Equipment</option>
|
||||
<option value="@NodeAclScopeKind.FolderSegment">FolderSegment</option>
|
||||
<option value="@NodeAclScopeKind.FolderSegment">FolderSegment (retired — do not author)</option>
|
||||
<option value="@NodeAclScopeKind.Tag">Tag</option>
|
||||
<option value="@NodeAclScopeKind.RawFolder">RawFolder</option>
|
||||
<option value="@NodeAclScopeKind.RawDriver">RawDriver</option>
|
||||
<option value="@NodeAclScopeKind.RawDevice">RawDevice</option>
|
||||
<option value="@NodeAclScopeKind.RawTagGroup">RawTagGroup</option>
|
||||
</InputSelect>
|
||||
</div>
|
||||
<div class="col-md-6 mb-3">
|
||||
<label class="form-label" for="target">Scope target ID</label>
|
||||
<InputText id="target" @bind-Value="_form.ScopeId" class="form-control form-control-sm mono"
|
||||
placeholder="Leave blank for cluster-wide" />
|
||||
<div class="form-text">
|
||||
Free text, no picker — a typo saves a grant that resolves to nothing.
|
||||
<span class="mono">Cluster</span> → leave blank ·
|
||||
<span class="mono">Namespace</span> → <span class="mono">raw</span> or
|
||||
<span class="mono">uns</span> ·
|
||||
<span class="mono">UnsArea</span> → a UnsAreaId ·
|
||||
<span class="mono">UnsLine</span> → a UnsLineId ·
|
||||
<span class="mono">Equipment</span> → an EquipmentId ·
|
||||
<span class="mono">Tag</span> → a TagId (a raw tag; the grant covers the raw
|
||||
node and every UNS projection of it) ·
|
||||
<span class="mono">RawFolder</span> → a RawFolderId ·
|
||||
<span class="mono">RawDriver</span> → a DriverInstanceId ·
|
||||
<span class="mono">RawDevice</span> → a DeviceId ·
|
||||
<span class="mono">RawTagGroup</span> → a TagGroupId ·
|
||||
<span class="mono">FolderSegment</span> → retired v2 kind, resolves nothing.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="mb-3">
|
||||
|
||||
@@ -20,29 +20,42 @@
|
||||
else
|
||||
{
|
||||
<div class="alert alert-warning" role="alert">
|
||||
<strong>These rules are not enforced.</strong>
|
||||
ACL rows are saved and shipped in every deployment artifact, but the OPC UA server never
|
||||
evaluates them — the permission evaluator has no production call site. Authoring a grant here
|
||||
changes nothing about what a client can read or write.
|
||||
<strong>Only <span class="mono">Cluster</span>-scoped grants are enforced today.</strong>
|
||||
A Cluster-scoped row confers a server-wide role on its principal:
|
||||
<span class="mono">WriteOperate</span> → writing any tag value;
|
||||
<span class="mono">AlarmAcknowledge</span> → the Part 9 alarm methods
|
||||
(acknowledge / confirm / shelve). No other permission bit is evaluated yet.
|
||||
<br />
|
||||
What <em>is</em> enforced today is coarse and fleet-wide: a client needs the
|
||||
<span class="mono">WriteOperate</span> role to write any tag and
|
||||
<span class="mono">AlarmAck</span> to acknowledge any alarm, both mapped from LDAP groups via
|
||||
<span class="mono">Security:Ldap:GroupToRole</span>. Reads, browses, subscriptions and history
|
||||
reads are <strong>not</strong> restricted at all. See <span class="mono">docs/security.md</span>.
|
||||
<strong>Narrower grants confer nothing.</strong>
|
||||
<span class="mono">Namespace</span>, <span class="mono">UnsArea</span>,
|
||||
<span class="mono">UnsLine</span>, <span class="mono">Equipment</span>,
|
||||
<span class="mono">Tag</span> and the <span class="mono">Raw*</span> kinds are saved and shipped
|
||||
in every deployment artifact, but stay inert until per-node enforcement lands. That
|
||||
under-granting is deliberate: honouring such a grant's flags while its <em>scope</em> cannot be
|
||||
honoured would turn "WriteOperate on one equipment" into server-wide write authority.
|
||||
<br />
|
||||
Read, Browse, Subscribe and HistoryRead are <strong>not</strong> gated for any admitted
|
||||
session, including anonymous.
|
||||
<br />
|
||||
Identity is an <strong>API key</strong>, not LDAP: a client presents an OPC UA UserName token
|
||||
with username <span class="mono">apikey</span> and password
|
||||
<span class="mono">otua_<keyId>_<secret></span>, and the key resolves to the
|
||||
principal named on these rows. Mint keys on the <span class="mono">/apikeys</span> page; LDAP
|
||||
now covers AdminUI login only. See <span class="mono">docs/security.md</span>.
|
||||
</div>
|
||||
|
||||
<section class="panel notice rise" style="animation-delay:.02s">
|
||||
ACL rows grant principals specific <span class="mono">NodePermissions</span> on a scope
|
||||
(a folder, an equipment, a tag). Per-cluster role grants were dropped in favour of
|
||||
fleet-wide LDAP-group → role mapping; ACLs here are the finer-grained per-node scope.
|
||||
(the cluster, a namespace, an area, an equipment, a raw device, a tag). A principal is an API
|
||||
key's principal, or the reserved <span class="mono">anonymous</span> principal that an
|
||||
anonymous session authenticates as.
|
||||
</section>
|
||||
|
||||
<section class="panel rise mt-3" style="animation-delay:.08s">
|
||||
<div class="panel-head">@_rows.Count ACL row@(_rows.Count == 1 ? "" : "s")</div>
|
||||
@if (_rows.Count == 0)
|
||||
{
|
||||
<div style="padding:1rem" class="text-muted">No ACL rows for this cluster — default permissions from the fleet-wide LDAP group mapping apply.</div>
|
||||
<div style="padding:1rem" class="text-muted">No ACL rows for this cluster — no principal holds <span class="mono">WriteOperate</span> or <span class="mono">AlarmAck</span> here, so writes and alarm acknowledges are refused. Reads, browses, subscriptions and history reads are unaffected.</div>
|
||||
}
|
||||
else
|
||||
{
|
||||
|
||||
@@ -61,10 +61,20 @@ public sealed class ArtifactApiKeyStore : IApiKeyStore
|
||||
Task.FromResult(ClusterGrants(_authority.Current, principal));
|
||||
|
||||
/// <summary>
|
||||
/// Narrows a principal's grants to the Cluster-scoped ones, matching <c>ConfigDbApiKeyStore</c>.
|
||||
/// Only those confer an interim role (see <see cref="ApiKeyInterimRoleMapper"/>); stage 5 widens
|
||||
/// both stores to the full grant set once scope is actually enforced.
|
||||
/// Narrows a principal's grants to the Cluster-scoped ones. Only those confer an interim role
|
||||
/// (see <see cref="ApiKeyInterimRoleMapper"/>); stage 5 widens both stores to the full grant set
|
||||
/// once scope is actually enforced.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <b>Scope kind is the ONLY narrowing needed here — cluster confinement already happened.</b>
|
||||
/// <c>DeploymentArtifact.ParseDataPlaneAuthority</c> kept only the node's own cluster's ACL rows
|
||||
/// (<c>ClusterFilterMode.ScopeTo</c>, matched <see cref="StringComparison.OrdinalIgnoreCase"/>),
|
||||
/// so this snapshot cannot contain another cluster's grant. <c>ConfigDbApiKeyStore</c> reads the
|
||||
/// fleet-wide ConfigDb and therefore has to apply that confinement itself; the two stores agree on
|
||||
/// the outcome, not on the mechanism. An earlier version of this comment claimed
|
||||
/// <c>ConfigDbApiKeyStore</c> "filters the same way in SQL" — it did not filter on cluster at all,
|
||||
/// which was the cross-cluster over-grant this remark now exists to keep straight.
|
||||
/// </remarks>
|
||||
private static IReadOnlyList<NodeAcl> ClusterGrants(DataPlaneAuthoritySnapshot snapshot, string principal)
|
||||
{
|
||||
var all = snapshot.GrantsFor(principal);
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
using Microsoft.EntityFrameworkCore;
|
||||
using ZB.MOM.WW.OtOpcUa.Cluster;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
@@ -16,6 +17,13 @@ namespace ZB.MOM.WW.OtOpcUa.Host.OpcUa;
|
||||
/// Reading per request is what makes revocation immediate here, which is why this store is
|
||||
/// preferred wherever a ConfigDb exists — including on a fused admin+driver node.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// ⚠️ <b>The ConfigDb holds the WHOLE fleet's ACL rows, not just this node's cluster's.</b> That is
|
||||
/// the difference from <see cref="ArtifactApiKeyStore"/>, whose snapshot was already narrowed to
|
||||
/// the node's own cluster by <c>DeploymentArtifact.ParseDataPlaneAuthority</c>. So this store must
|
||||
/// confine grants to <see cref="ClusterId"/> itself — without that predicate a Cluster-scoped
|
||||
/// grant authored in ANY cluster in the fleet conferred an interim server-wide role here.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class ConfigDbApiKeyStore : IApiKeyStore
|
||||
{
|
||||
@@ -23,7 +31,57 @@ public sealed class ConfigDbApiKeyStore : IApiKeyStore
|
||||
|
||||
/// <summary>Initializes a new instance of the <see cref="ConfigDbApiKeyStore"/> class.</summary>
|
||||
/// <param name="factory">The config DB context factory.</param>
|
||||
public ConfigDbApiKeyStore(IDbContextFactory<OtOpcUaConfigDbContext> factory) => _factory = factory;
|
||||
/// <param name="clusterId">
|
||||
/// This node's own ClusterId, from <see cref="ResolveClusterId"/>. <see langword="null"/> on a
|
||||
/// legacy / single-cluster node that carries no <c>cluster-{ClusterId}</c> role — see
|
||||
/// <see cref="ClusterId"/> for what that means for filtering.
|
||||
/// </param>
|
||||
public ConfigDbApiKeyStore(IDbContextFactory<OtOpcUaConfigDbContext> factory, string? clusterId)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(factory);
|
||||
_factory = factory;
|
||||
ClusterId = string.IsNullOrWhiteSpace(clusterId) ? null : clusterId;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The node's own ClusterId, or <see langword="null"/> when it carries no cluster-scoped role.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// A <see langword="null"/> ClusterId applies NO cluster filter, mirroring the artifact path's
|
||||
/// <c>ClusterFilterMode.None</c> — a single-cluster artifact is applied whole. Failing closed here
|
||||
/// instead would silently strip every grant on an existing single-cluster deployment, which is a
|
||||
/// worse failure than the one being fixed and would not be visible until a client was denied.
|
||||
/// </remarks>
|
||||
public string? ClusterId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Resolves the node's ClusterId from its OWN configured roles, e.g. <c>cluster-SITE-A</c> →
|
||||
/// <c>SITE-A</c>; <see langword="null"/> when no role is cluster-scoped.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is the same derivation <see cref="Cluster.ClusterRoleInfo"/> performs for
|
||||
/// <c>IClusterRoleInfo.ClusterId</c>, reusing the same <see cref="RoleParser"/> primitives —
|
||||
/// first cluster-scoped role wins, as it does there.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// ⚠️ <b>Takes <see cref="AkkaClusterOptions"/> (pure configuration), NOT
|
||||
/// <c>IClusterRoleInfo</c> resolved from the service provider.</b> <c>ClusterRoleInfo</c>
|
||||
/// depends on the <c>ActorSystem</c>; resolving it during host composition recurses into
|
||||
/// ActorSystem construction and stack-overflows the node at boot while compiling clean (see
|
||||
/// CLAUDE.md, per-cluster mesh Phase 6). The ClusterId is configuration, so read it from
|
||||
/// configuration.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="options">The node's bound cluster options.</param>
|
||||
/// <returns>The node's ClusterId, or <see langword="null"/> when it carries no cluster-scoped role.</returns>
|
||||
public static string? ResolveClusterId(AkkaClusterOptions options)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(options);
|
||||
|
||||
var clusterRole = options.Roles.FirstOrDefault(RoleParser.IsClusterRole);
|
||||
return clusterRole is null ? null : RoleParser.ClusterIdFromRole(clusterRole);
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public async Task<ApiKeyLookup?> FindAsync(string apiKeyId, DateTime utcNow, CancellationToken ct)
|
||||
@@ -53,15 +111,33 @@ public sealed class ConfigDbApiKeyStore : IApiKeyStore
|
||||
return await LoadClusterGrantsAsync(db, principal, ct).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static async Task<IReadOnlyList<NodeAcl>> LoadClusterGrantsAsync(
|
||||
private async Task<IReadOnlyList<NodeAcl>> LoadClusterGrantsAsync(
|
||||
OtOpcUaConfigDbContext db, string principal, CancellationToken ct)
|
||||
{
|
||||
// Only cluster-scoped rows can confer an interim role (see ApiKeyInterimRoleMapper), so only
|
||||
// those are fetched. Stage 5 widens this to the full grant set for per-node evaluation.
|
||||
return await db.NodeAcls
|
||||
var rows = await db.NodeAcls
|
||||
.AsNoTracking()
|
||||
.Where(a => a.Principal == principal && a.ScopeKind == NodeAclScopeKind.Cluster)
|
||||
.ToListAsync(ct)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
if (ClusterId is null) return rows;
|
||||
|
||||
// The ClusterId match is done HERE rather than as a SQL predicate, unlike the Enabled/expiry
|
||||
// filters above, because it must be case-insensitive DETERMINISTICALLY. `a.ClusterId == ...` in
|
||||
// SQL is decided by the database collation — case-insensitive on the usual SQL Server default,
|
||||
// case-SENSITIVE on a CS collation or on the in-memory provider the tests use — and the two
|
||||
// spellings genuinely differ: `Cluster:Roles` binds a role verbatim (cluster-SITE-A ⇒ SITE-A)
|
||||
// while the OTOPCUA_ROLES path goes through RoleParser.Parse, which lower-cases it (⇒ site-a).
|
||||
// A collation-dependent match would therefore strip every grant on a node configured the second
|
||||
// way. OrdinalIgnoreCase is the SAME comparison DeploymentArtifact.ParseDataPlaneAuthority uses
|
||||
// to scope the artifact's grants, so both stores confine identically.
|
||||
var mine = new List<NodeAcl>(rows.Count);
|
||||
foreach (var grant in rows)
|
||||
{
|
||||
if (string.Equals(grant.ClusterId, ClusterId, StringComparison.OrdinalIgnoreCase)) mine.Add(grant);
|
||||
}
|
||||
return mine;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -376,7 +376,15 @@ if (hasDriver)
|
||||
// A node WITH a ConfigDb reads keys straight from it, which is what makes revocation take effect
|
||||
// on the very next request rather than on the next deployment. Preferred wherever it is available,
|
||||
// including on a fused admin+driver node.
|
||||
builder.Services.AddSingleton<IApiKeyStore, ConfigDbApiKeyStore>();
|
||||
// The ClusterId confines the grants this node honours to its OWN cluster — the ConfigDb holds
|
||||
// the whole fleet's ACL rows, unlike the artifact a driver-only node reads, which
|
||||
// ParseDataPlaneAuthority already scoped. Taken from AkkaClusterOptions (pure configuration),
|
||||
// NOT from IClusterRoleInfo: that depends on the ActorSystem, and the same options-not-services
|
||||
// rule is what keeps the redundancy-singleton registration below from recursing into ActorSystem
|
||||
// construction. Null on a node with no cluster-{ClusterId} role ⇒ no filter (legacy behaviour).
|
||||
builder.Services.AddSingleton<IApiKeyStore>(sp => new ConfigDbApiKeyStore(
|
||||
sp.GetRequiredService<IDbContextFactory<OtOpcUaConfigDbContext>>(),
|
||||
ConfigDbApiKeyStore.ResolveClusterId(sp.GetRequiredService<IOptions<AkkaClusterOptions>>().Value)));
|
||||
builder.Services.AddSingleton<IOpcUaUserAuthenticator, ApiKeyOpcUaUserAuthenticator>();
|
||||
|
||||
// Minting surface for the AdminUI. Same node condition as the store above: both need a ConfigDb.
|
||||
|
||||
@@ -4,6 +4,7 @@ using ZB.MOM.WW.OtOpcUa.Commons.Types;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
using ZB.MOM.WW.OtOpcUa.OpcUaServer;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
|
||||
@@ -46,13 +47,22 @@ public enum ClusterFilterMode
|
||||
/// lookup filters those, so that a revocation is visible rather than indistinguishable from a
|
||||
/// missing key.</param>
|
||||
/// <param name="Grants">The <c>NodeAcl</c> rows scoped to <paramref name="ClusterId"/>.</param>
|
||||
/// <param name="ScopePaths">
|
||||
/// Where each grant's scope sits in the address space, resolved from the artifact's own topology.
|
||||
/// This is why the node needs no ConfigDb to build a permission trie: the artifact already carries
|
||||
/// every raw and UNS parent link, so the paths are derivable from the same bytes the grants came in.
|
||||
/// A scope that resolves to nothing is absent here, and the trie builder drops its grant with a
|
||||
/// diagnostic rather than planting it somewhere unreachable.
|
||||
/// </param>
|
||||
public sealed record DataPlaneAuthorityProjection(
|
||||
string? ClusterId,
|
||||
IReadOnlyList<ApiKey> Keys,
|
||||
IReadOnlyList<NodeAcl> Grants)
|
||||
IReadOnlyList<NodeAcl> Grants,
|
||||
IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> ScopePaths)
|
||||
{
|
||||
/// <summary>The projection of an absent or unparseable artifact: no cluster, no keys, no grants.</summary>
|
||||
public static readonly DataPlaneAuthorityProjection Empty = new(null, [], []);
|
||||
public static readonly DataPlaneAuthorityProjection Empty =
|
||||
new(null, [], [], new Dictionary<AclScopeRef, IReadOnlyList<NodeAclPath>>());
|
||||
}
|
||||
|
||||
/// <summary>Resolved scoping decision for a node against an artifact.</summary>
|
||||
@@ -610,7 +620,8 @@ public static class DeploymentArtifact
|
||||
grants.Add(acl);
|
||||
}
|
||||
|
||||
return new DataPlaneAuthorityProjection(scope.ClusterId, keys, grants);
|
||||
return new DataPlaneAuthorityProjection(
|
||||
scope.ClusterId, keys, grants, BuildAclScopePaths(root, grants));
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
@@ -618,6 +629,109 @@ public static class DeploymentArtifact
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Resolve every scope named by <paramref name="grants"/> against the artifact's own raw + UNS
|
||||
/// topology, using the same <c>RawPathResolver</c> the address space is built through — so an ACL
|
||||
/// path and the RawPath that forms a node's NodeId cannot drift apart.
|
||||
/// </summary>
|
||||
private static IReadOnlyDictionary<AclScopeRef, IReadOnlyList<NodeAclPath>> BuildAclScopePaths(
|
||||
JsonElement root,
|
||||
IReadOnlyList<NodeAcl> grants)
|
||||
{
|
||||
if (grants.Count == 0) return new Dictionary<AclScopeRef, IReadOnlyList<NodeAclPath>>();
|
||||
|
||||
var folders = new Dictionary<string, (string? ParentId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "RawFolders"))
|
||||
{
|
||||
var id = ReadString(el, "RawFolderId");
|
||||
if (id is null) continue;
|
||||
folders[id] = (ReadNullableString(el, "ParentRawFolderId"), ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var drivers = new Dictionary<string, (string? RawFolderId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "DriverInstances"))
|
||||
{
|
||||
var id = ReadString(el, "DriverInstanceId");
|
||||
if (id is null) continue;
|
||||
drivers[id] = (ReadNullableString(el, "RawFolderId"), ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var devices = new Dictionary<string, (string DriverInstanceId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "Devices"))
|
||||
{
|
||||
var id = ReadString(el, "DeviceId");
|
||||
var driverId = ReadString(el, "DriverInstanceId");
|
||||
if (id is null || driverId is null) continue;
|
||||
devices[id] = (driverId, ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var groups = new Dictionary<string, (string? ParentId, string DeviceId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "TagGroups"))
|
||||
{
|
||||
var id = ReadString(el, "TagGroupId");
|
||||
var deviceId = ReadString(el, "DeviceId");
|
||||
if (id is null || deviceId is null) continue;
|
||||
groups[id] = (ReadNullableString(el, "ParentTagGroupId"), deviceId, ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var tags = new Dictionary<string, (string DeviceId, string? TagGroupId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "Tags"))
|
||||
{
|
||||
var id = ReadString(el, "TagId");
|
||||
var deviceId = ReadString(el, "DeviceId");
|
||||
if (id is null || deviceId is null) continue;
|
||||
tags[id] = (deviceId, ReadNullableString(el, "TagGroupId"), ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var areas = new Dictionary<string, string>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "UnsAreas"))
|
||||
{
|
||||
var id = ReadString(el, "UnsAreaId");
|
||||
if (id is null) continue;
|
||||
areas[id] = ReadString(el, "Name") ?? id;
|
||||
}
|
||||
|
||||
var lines = new Dictionary<string, (string UnsAreaId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "UnsLines"))
|
||||
{
|
||||
var id = ReadString(el, "UnsLineId");
|
||||
var areaId = ReadString(el, "UnsAreaId");
|
||||
if (id is null || areaId is null) continue;
|
||||
lines[id] = (areaId, ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var equipment = new Dictionary<string, (string UnsLineId, string Name)>(StringComparer.Ordinal);
|
||||
foreach (var el in EnumerateArray(root, "Equipment"))
|
||||
{
|
||||
var id = ReadString(el, "EquipmentId");
|
||||
var lineId = ReadString(el, "UnsLineId");
|
||||
if (id is null || lineId is null) continue;
|
||||
equipment[id] = (lineId, ReadString(el, "Name") ?? id);
|
||||
}
|
||||
|
||||
var references = new List<(string EquipmentId, string TagId, string EffectiveName)>();
|
||||
foreach (var el in EnumerateArray(root, "UnsTagReferences"))
|
||||
{
|
||||
var equipmentId = ReadString(el, "EquipmentId");
|
||||
var tagId = ReadString(el, "TagId");
|
||||
if (equipmentId is null || tagId is null) continue;
|
||||
|
||||
// Effective name = the override when present, else the backing raw tag's own name. This is the
|
||||
// same rule the address space materializes UNS variables under; a reference whose tag is
|
||||
// missing from the artifact has no resolvable name and is skipped.
|
||||
var effective = ReadNullableString(el, "DisplayNameOverride");
|
||||
if (string.IsNullOrWhiteSpace(effective))
|
||||
effective = tags.TryGetValue(tagId, out var t) ? t.Name : null;
|
||||
if (effective is null) continue;
|
||||
|
||||
references.Add((equipmentId, tagId, effective));
|
||||
}
|
||||
|
||||
var resolver = new AclScopePathResolver(
|
||||
folders, drivers, devices, groups, tags, areas, lines, equipment, references);
|
||||
return resolver.Resolve(grants);
|
||||
}
|
||||
|
||||
/// <summary>Reads one <c>ApiKeys</c> element; null when a field the credential check depends on is
|
||||
/// missing, so a half-written row can never authenticate.</summary>
|
||||
private static ApiKey? TryReadApiKey(JsonElement el)
|
||||
|
||||
@@ -9,6 +9,7 @@ using ZB.MOM.WW.OtOpcUa.Commons.Observability;
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.Types;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration;
|
||||
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Authorization;
|
||||
using ZB.MOM.WW.OtOpcUa.OpcUaServer;
|
||||
using ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
|
||||
@@ -533,12 +534,29 @@ public sealed class OpcUaPublishActor : ReceiveActor, IWithTimers
|
||||
// which is what lets a node recognise a re-applied revision without the hash riding the wire.
|
||||
var revision = Convert.ToHexStringLower(System.Security.Cryptography.SHA256.HashData(artifact));
|
||||
var snapshot = _dataPlaneAuthority.Apply(
|
||||
projection.ClusterId, revision, projection.Keys, projection.Grants);
|
||||
projection.ClusterId, revision, projection.Keys, projection.Grants, projection.ScopePaths);
|
||||
|
||||
// unresolvedScopes counts grants narrower than Cluster whose ScopeId named nothing in this
|
||||
// artifact — a dangling id, or a scope kind with no v3 entity behind it. Those grants will be
|
||||
// dropped when the trie is built, so surfacing the count here is the operator's only warning
|
||||
// that a rule they authored is not going to do anything.
|
||||
var unresolvedScopes = projection.Grants
|
||||
.Where(g => g.ScopeKind != NodeAclScopeKind.Cluster && !string.IsNullOrEmpty(g.ScopeId))
|
||||
.Select(g => new AclScopeRef(g.ScopeKind, g.ScopeId!))
|
||||
.Distinct()
|
||||
.Count(r => !projection.ScopePaths.ContainsKey(r));
|
||||
|
||||
_log.Info(
|
||||
"OpcUaPublish: data-plane authority generation {Generation} installed (cluster={Cluster}, revision={Revision}, keys={Keys}, grants={Grants})",
|
||||
"OpcUaPublish: data-plane authority generation {Generation} installed (cluster={Cluster}, revision={Revision}, keys={Keys}, grants={Grants}, resolvedScopes={ResolvedScopes})",
|
||||
snapshot.GenerationId, projection.ClusterId ?? "(single-cluster)", revision[..12],
|
||||
projection.Keys.Count, projection.Grants.Count);
|
||||
projection.Keys.Count, projection.Grants.Count, projection.ScopePaths.Count);
|
||||
|
||||
if (unresolvedScopes > 0)
|
||||
{
|
||||
_log.Warning(
|
||||
"OpcUaPublish: {Unresolved} ACL scope(s) in generation {Generation} name nothing in the deployed address space — grants on them will be DROPPED, not applied. Check the ScopeId on those rules",
|
||||
unresolvedScopes, snapshot.GenerationId);
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user