Files
lmxopcua/src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/ApiKeyInterimRoleMapper.cs
T
Joseph Doherty 826312befe docs: fill missing XML docs and strip tracking IDs from src comments
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
2026-10-15 06:14:58 -04:00

72 lines
3.8 KiB
C#

using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
using ZB.MOM.WW.OtOpcUa.OpcUaServer.Security;
namespace ZB.MOM.WW.OtOpcUa.Host.OpcUa;
/// <summary>
/// Derives the interim server-wide role set for an authenticated principal from its
/// <see cref="NodeAcl"/> grants.
/// </summary>
/// <remarks>
/// <para>
/// <b>Why this exists at all.</b> The two live authorization gates —
/// <see cref="OpcUaDataPlaneRoles.WriteOperate"/> on Value writes and
/// <see cref="OpcUaDataPlaneRoles.AlarmAck"/> on the Part 9 alarm methods — check a server-wide
/// role set on the session identity. Replacing LDAP with API keys therefore has to keep
/// producing that role set, or the cutover would lock every client out of writes and alarm acks
/// long before per-node ACL evaluation lands in stage 5.
/// </para>
/// <para>
/// ⚠️ <b>Only <see cref="NodeAclScopeKind.Cluster"/> grants confer a role. This is deliberate,
/// and it under-grants.</b> The obvious implementation — union the permission flags across all of
/// a principal's grants — would let a grant authored narrowly ("WriteOperate on Equipment X")
/// confer the server-wide WriteOperate role, because nothing here can enforce scope yet. That
/// fails in the dangerous direction: the operator's narrow intent silently becomes broad
/// authority. Restricting to cluster-scoped grants means a narrow grant does nothing until
/// stage 5 can honour its scope, which is no worse than today (where every ACL row does
/// nothing) and never exceeds what was authored.
/// </para>
/// <para>
/// Scope-narrower-than-cluster grants are not an error and are not logged as one — they are
/// simply inert until enforcement lands. The AdminUI banner is where an operator is told that.
/// </para>
/// </remarks>
public static class ApiKeyInterimRoleMapper
{
/// <summary>
/// Maps a principal's cluster-scoped grants to the server-wide data-plane roles.
/// </summary>
/// <param name="grants">Candidate ACL rows. Rows for other principals are ignored.</param>
/// <param name="principal">The authenticated principal.</param>
/// <returns>The distinct role names to attach to the session identity; never null.</returns>
public static IReadOnlyList<string> Map(IEnumerable<NodeAcl> grants, string principal)
{
ArgumentNullException.ThrowIfNull(grants);
if (string.IsNullOrWhiteSpace(principal)) return Array.Empty<string>();
var effective = NodePermissions.None;
foreach (var grant in grants)
{
if (grant.ScopeKind != NodeAclScopeKind.Cluster) continue;
if (!string.Equals(grant.Principal, principal, StringComparison.OrdinalIgnoreCase)) continue;
effective |= grant.PermissionFlags;
}
var roles = new List<string>(3);
if (effective.HasFlag(NodePermissions.WriteOperate)) roles.Add(OpcUaDataPlaneRoles.WriteOperate);
// AlarmAcknowledge is the flag an operator authors; AlarmAck is the role the Part 9 method gates
// check. The gate covers acknowledge/confirm/shelve as one role, so Confirm/Shelve do not map
// separately — mapping them would imply a granularity the gate does not have.
if (effective.HasFlag(NodePermissions.AlarmAcknowledge)) roles.Add(OpcUaDataPlaneRoles.AlarmAck);
// HistoryUpdate has its own role: WriteOperate (live writes) never implies authority to rewrite
// recorded history, so the role is conferred by the HistoryUpdate flag alone.
if (effective.HasFlag(NodePermissions.HistoryUpdate)) roles.Add(OpcUaDataPlaneRoles.HistoryUpdate);
return roles;
}
}