feat(acl): anonymous becomes a normal grantable principal (#520 D3)

Anonymous sessions used to short-circuit in HandleImpersonation — "let the SDK's
default validation stand" — so they always connected and always carried no roles.
Now admission and authority are separated:

  admission  -> OpcUa:AllowAnonymous, the HOST's decision (it owns token policies)
  authority  -> the authenticator, resolving the reserved principal "anonymous"
                through the SAME grant path a key's principal goes through

So anonymous can be granted WRITE, not merely tolerated as read-only, and it
arrives at the downstream gates as the same RoleCarryingUserIdentity a key
produces — which is the real payoff: no gate carries an anonymous-shaped branch,
so there is no bypass path to get wrong.

AllowAnonymous defaults to TRUE on purpose. Defaulting it false would silently
deny every client without a key the moment this deploys, including ScadaBridge's
Data Connection Layer in another repo. Making keys mandatory is a rollout
decision, not an upgrade side effect. When false, the Anonymous token policy is
withheld so a client is refused at DISCOVERY rather than only at activation, and
activation is rejected independently in case a client attempts a token type the
endpoint never advertised.

Two fail-closed choices, both falsified:
- A failure to read anonymous's grants DENIES rather than admitting with no
  roles. Admitting is the pre-#520 behaviour, and defaulting to it exactly when
  the server cannot determine what anonymous may do stops being harmless once
  reads are gated. Making it admit reds Anonymous_denies_when_grants_cannot_be_read.
- A key may not authenticate as the reserved "anonymous" principal, or a
  credentialled client silently inherits whatever anonymous was granted.

AuthenticateAnonymousAsync is a DEFAULT interface implementation returning
admit-with-no-roles, i.e. exactly the pre-#520 behaviour, so
NullOpcUaUserAuthenticator and every test double keep working rather than being
forced to reimplement it — important because driver-only nodes run the Null one
and would otherwise black out. Note a default interface method is only reachable
through the interface-typed reference, which is how OpcUaApplicationHost holds it.

An existing test asserted the old fall-through and correctly went red; it is
rewritten to pin the new contract rather than deleted, with the reason recorded.

OpcUaServer 366, Host 42 green.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo

src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/ApiKeyOpcUaUserAuthenticator.cs

@@ -1,5 +1,8 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
+// Explicit: an unqualified Configuration.* inside this namespace binds to Host.Configuration, not to
+// the ZB.MOM.WW.OtOpcUa.Configuration assembly.
+using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
 using ZB.MOM.WW.OtOpcUa.Core.Authorization;
 using ZB.MOM.WW.OtOpcUa.OpcUaServer.Security;
 
@@ -120,6 +123,17 @@ public sealed class ApiKeyOpcUaUserAuthenticator : IOpcUaUserAuthenticator
             return OpcUaUserAuthResult.Deny(DenyMessage);
         }
 
+        if (string.Equals(lookup.Key.Principal, OpcUaPrincipals.Anonymous, StringComparison.OrdinalIgnoreCase))
+        {
+            // Defence in depth against a key authored with the reserved principal (authoring blocks it).
+            // Allowing it would let a credentialled client silently inherit whatever anonymous was
+            // granted, and vice versa — two identities that are meant to be distinct sharing one grant.
+            _log.LogError(
+                "ApiKeyAuth: denied — key {ApiKeyId} uses the reserved principal '{Principal}'",
+                apiKeyId, OpcUaPrincipals.Anonymous);
+            return OpcUaUserAuthResult.Deny(DenyMessage);
+        }
+
         var roles = ApiKeyInterimRoleMapper.Map(lookup.Grants, lookup.Key.Principal);
 
         _log.LogInformation(
@@ -128,4 +142,35 @@ public sealed class ApiKeyOpcUaUserAuthenticator : IOpcUaUserAuthenticator
 
         return OpcUaUserAuthResult.Allow(lookup.Key.Principal, roles);
     }
+
+    /// <inheritdoc />
+    /// <remarks>
+    ///     Resolves the <c>anonymous</c> principal's grants through the same mapper a key's principal
+    ///     goes through, so anonymous is authorized by ordinary ACL rows rather than by a special case.
+    ///     Whether anonymous may connect at all is the host's decision
+    ///     (<c>OpcUa:AllowAnonymous</c>) and is settled before this is called.
+    /// </remarks>
+    public async Task<OpcUaUserAuthResult> AuthenticateAnonymousAsync(CancellationToken ct)
+    {
+        IReadOnlyList<NodeAcl> grants;
+        try
+        {
+            grants = await _store.FindGrantsAsync(OpcUaPrincipals.Anonymous, ct).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            // Deny rather than admit-with-no-roles. Admitting would be the pre-#520 behaviour, and doing
+            // it precisely when we could not read what anonymous is allowed to do is the wrong default:
+            // once reads are gated (stage 6) a no-roles admission stops being harmless.
+            _log.LogError(ex, "ApiKeyAuth: key store threw resolving anonymous grants");
+            return OpcUaUserAuthResult.Deny("Anonymous access is unavailable.");
+        }
+
+        var roles = ApiKeyInterimRoleMapper.Map(grants, OpcUaPrincipals.Anonymous);
+        _log.LogInformation(
+            "ApiKeyAuth: anonymous admitted with roles [{Roles}]",
+            roles.Count == 0 ? "none" : string.Join(",", roles));
+
+        return OpcUaUserAuthResult.Allow(OpcUaPrincipals.Anonymous, roles);
+    }
 }

src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/ConfigDbApiKeyStore.cs

@@ -43,15 +43,25 @@ public sealed class ConfigDbApiKeyStore : IApiKeyStore
 
         if (key is null) return null;
 
+        return new ApiKeyLookup(key, await LoadClusterGrantsAsync(db, key.Principal, ct).ConfigureAwait(false));
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<NodeAcl>> FindGrantsAsync(string principal, CancellationToken ct)
+    {
+        await using var db = await _factory.CreateDbContextAsync(ct).ConfigureAwait(false);
+        return await LoadClusterGrantsAsync(db, principal, ct).ConfigureAwait(false);
+    }
+
+    private static 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.
-        var grants = await db.NodeAcls
+        return await db.NodeAcls
             .AsNoTracking()
-            .Where(a => a.Principal == key.Principal
-                        && a.ScopeKind == NodeAclScopeKind.Cluster)
+            .Where(a => a.Principal == principal && a.ScopeKind == NodeAclScopeKind.Cluster)
             .ToListAsync(ct)
             .ConfigureAwait(false);
-
-        return new ApiKeyLookup(key, grants);
     }
 }

src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/IApiKeyStore.cs

@@ -22,6 +22,15 @@ public interface IApiKeyStore
     /// <param name="ct">The cancellation token.</param>
     /// <returns>The key and its principal's grants, or null when no usable key matches.</returns>
     Task<ApiKeyLookup?> FindAsync(string apiKeyId, DateTime utcNow, CancellationToken ct);
+
+    /// <summary>
+    ///     Returns the ACL grants naming a principal, with no key involved. Used for the
+    ///     <c>anonymous</c> principal, which has grants but obviously no credential.
+    /// </summary>
+    /// <param name="principal">The principal to fetch grants for.</param>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>The matching ACL rows; empty when none.</returns>
+    Task<IReadOnlyList<NodeAcl>> FindGrantsAsync(string principal, CancellationToken ct);
 }
 
 /// <summary>An API key resolved for authentication, with the ACL grants naming its principal.</summary>

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs

@@ -51,6 +51,29 @@ public sealed class OpcUaApplicationHostOptions
     /// </summary>
     public string PkiStoreRoot { get; set; } = "pki";
 
+    /// <summary>
+    ///     Whether anonymous sessions may connect at all (#520). When <see langword="false"/> the
+    ///     Anonymous token policy is not advertised AND anonymous activation is rejected, so a client
+    ///     must present an API key.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <b>Defaults to <see langword="true"/> deliberately, which preserves today's behaviour.</b>
+    ///         Flipping the default would silently deny every client that has no key the moment this
+    ///         code deploys — including ScadaBridge's Data Connection Layer, which consumes this address
+    ///         space from another repo. Turning it off is the deployment-time decision that makes keys
+    ///         mandatory, and it belongs in the rollout once keys have been issued.
+    ///     </para>
+    ///     <para>
+    ///         Note this controls <i>admission</i>, not authority. An admitted anonymous session is a
+    ///         normal principal (<c>anonymous</c>) whose grants come from <c>NodeAcl</c> rows naming it,
+    ///         exactly like a key's principal — there is no anonymous bypass branch in the evaluator.
+    ///         Until per-node enforcement lands, an admitted session of ANY kind can still read the whole
+    ///         address space, because reads carry no authorization check yet.
+    ///     </para>
+    /// </remarks>
+    public bool AllowAnonymous { get; set; } = true;
+
     /// <summary>
     /// Transport-security profiles exposed by the server. The SDK publishes one endpoint
     /// descriptor per profile and clients choose at session open. Default = all three
@@ -228,7 +251,7 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
     }
 
     private void OnImpersonateUser(ISession session, ImpersonateEventArgs args) =>
-        HandleImpersonation(_userAuthenticator, args, _logger);
+        HandleImpersonation(_userAuthenticator, args, _logger, _options.AllowAnonymous);
 
     /// <summary>
     /// Pure(-ish) impersonation handler: extracted so unit tests can drive it without booting
@@ -256,11 +279,18 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
     internal static void HandleImpersonation(
         IOpcUaUserAuthenticator authenticator,
         ImpersonateEventArgs args,
-        ILogger logger)
+        ILogger logger,
+        bool allowAnonymous = true)
     {
+        if (args.NewIdentity is AnonymousIdentityToken anonymousToken)
+        {
+            HandleAnonymousImpersonation(authenticator, args, logger, allowAnonymous, anonymousToken);
+            return;
+        }
+
         if (args.NewIdentity is not UserNameIdentityToken token)
         {
-            // Anonymous + X509 tokens — let the SDK's default validation stand.
+            // X509 tokens — let the SDK's default validation stand.
             return;
         }
 
@@ -309,6 +339,66 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
             token.UserName, string.Join(",", result.Roles));
     }
 
+    /// <summary>
+    ///     Admits or rejects an anonymous session, and — when admitted — attaches the roles the
+    ///     <c>anonymous</c> principal has been granted (#520).
+    /// </summary>
+    /// <remarks>
+    ///     Before #520 this path simply returned, leaving the SDK's default identity in place: anonymous
+    ///     always connected and carried no roles. Two things change. Anonymous can now be refused
+    ///     outright, and when admitted it is a normal principal whose grants come from ACL rows, so it
+    ///     can be given read or write like any key. The identity attached is the same
+    ///     <see cref="RoleCarryingUserIdentity"/> the UserName path uses, so every downstream gate reads
+    ///     it identically and there is no anonymous-shaped branch in any of them.
+    /// </remarks>
+    private static void HandleAnonymousImpersonation(
+        IOpcUaUserAuthenticator authenticator,
+        ImpersonateEventArgs args,
+        ILogger logger,
+        bool allowAnonymous,
+        AnonymousIdentityToken token)
+    {
+        if (!allowAnonymous)
+        {
+            logger.LogInformation(
+                "OpcUaApplicationHost: anonymous session rejected (OpcUa:AllowAnonymous is false)");
+            args.IdentityValidationError = new ServiceResult(StatusCodes.BadIdentityTokenRejected,
+                "Anonymous access is disabled on this server.");
+            return;
+        }
+
+        OpcUaUserAuthResult result;
+        try
+        {
+            // Same synchronous bridge, and for the same irreducible reason, as the UserName path above.
+            result = authenticator.AuthenticateAnonymousAsync(CancellationToken.None)
+                .GetAwaiter().GetResult();
+        }
+        catch (Exception ex)
+        {
+            // Fail closed. An anonymous session whose grants could not be resolved must not fall through
+            // to the SDK default identity, because that would silently ADMIT it — the pre-#520
+            // behaviour — at exactly the moment we could not determine what it is allowed to do.
+            logger.LogError(ex, "OpcUaApplicationHost: anonymous authenticator threw");
+            args.IdentityValidationError = new ServiceResult(StatusCodes.BadIdentityTokenRejected,
+                "Anonymous access is unavailable.");
+            return;
+        }
+
+        if (!result.Success)
+        {
+            logger.LogInformation("OpcUaApplicationHost: anonymous session denied: {Error}", result.Error);
+            args.IdentityValidationError = new ServiceResult(StatusCodes.BadIdentityTokenRejected,
+                result.Error ?? "Anonymous access is denied.");
+            return;
+        }
+
+        args.Identity = new RoleCarryingUserIdentity(token, result.Roles);
+        logger.LogInformation("OpcUaApplicationHost: anonymous session admitted as {Principal} ({Roles})",
+            OpcUaPrincipals.Anonymous,
+            result.Roles.Count == 0 ? "no roles" : string.Join(",", result.Roles));
+    }
+
     /// <summary>
     /// Guarantees the application instance certificate exists in <c>{PkiStoreRoot}/own</c>.
     /// The SDK auto-creates a self-signed certificate the first time this is called on a fresh
@@ -350,7 +440,7 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
         {
             serverConfig.SecurityPolicies.Add(policy);
         }
-        foreach (var token in BuildUserTokenPolicies())
+        foreach (var token in BuildUserTokenPolicies(_options.AllowAnonymous))
         {
             serverConfig.UserTokenPolicies.Add(token);
         }
@@ -442,13 +532,20 @@ public sealed class OpcUaApplicationHost : IAsyncDisposable
     /// UserName logins when none is registered.
     /// </summary>
     /// <returns>The Anonymous and UserName token policies.</returns>
-    internal static IEnumerable<UserTokenPolicy> BuildUserTokenPolicies()
+    internal static IEnumerable<UserTokenPolicy> BuildUserTokenPolicies(bool allowAnonymous = true)
     {
-        yield return new UserTokenPolicy(UserTokenType.Anonymous)
+        // Withholding the policy is what makes the refusal visible to a client at DISCOVERY rather than
+        // only at activation: it simply is not offered an anonymous option. HandleImpersonation still
+        // rejects anonymous activation independently, because a client may attempt a token type the
+        // endpoint never advertised.
+        if (allowAnonymous)
         {
-            PolicyId = "anonymous",
-            SecurityPolicyUri = SecurityPolicies.None,
-        };
+            yield return new UserTokenPolicy(UserTokenType.Anonymous)
+            {
+                PolicyId = "anonymous",
+                SecurityPolicyUri = SecurityPolicies.None,
+            };
+        }
         yield return new UserTokenPolicy(UserTokenType.UserName)
         {
             PolicyId = "username_basic256sha256",

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Security/IOpcUaUserAuthenticator.cs

@@ -22,6 +22,43 @@ public interface IOpcUaUserAuthenticator
     /// <param name="ct">The cancellation token.</param>
     /// <returns>An OpcUaUserAuthResult indicating success or failure.</returns>
     Task<OpcUaUserAuthResult> AuthenticateUserNameAsync(string username, string password, CancellationToken ct);
+
+    /// <summary>
+    ///     Resolves what an <b>anonymous</b> session is allowed to do (#520). Anonymous is a normal
+    ///     principal — <see cref="OpcUaPrincipals.Anonymous"/> — not a special case, so it can be granted
+    ///     read or write through ordinary ACL rows.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         This is asked only AFTER the host has decided anonymous sessions are admissible at all
+    ///         (<c>OpcUaApplicationHostOptions.AllowAnonymous</c>). Admission is the host's decision;
+    ///         authority is this seam's.
+    ///     </para>
+    ///     <para>
+    ///         The default implementation admits anonymous with <b>no roles</b>, which is exactly the
+    ///         behaviour before #520: an anonymous session connects, and every role-gated operation
+    ///         (write, alarm ack) denies. Implementors that can resolve grants override it; the rest
+    ///         keep the safe status quo rather than being forced to reimplement it.
+    ///     </para>
+    /// </remarks>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>The roles to attach to the anonymous session, or a denial.</returns>
+    Task<OpcUaUserAuthResult> AuthenticateAnonymousAsync(CancellationToken ct) =>
+        Task.FromResult(OpcUaUserAuthResult.Allow(OpcUaPrincipals.Anonymous, Array.Empty<string>()));
+}
+
+/// <summary>Reserved principal names for the OPC UA data plane (#520).</summary>
+public static class OpcUaPrincipals
+{
+    /// <summary>
+    ///     The principal an anonymous session authenticates as. <c>NodeAcl</c> rows naming it grant
+    ///     anonymous clients permissions exactly as they would a key's principal.
+    /// </summary>
+    /// <remarks>
+    ///     Reserved: an API key must not be created with this principal, or a key would silently inherit
+    ///     whatever anonymous was granted (and vice versa). Enforced at authoring time.
+    /// </remarks>
+    public const string Anonymous = "anonymous";
 }
 
 /// <summary>Outcome of a UserName authentication attempt. <see cref="Roles"/> populates the session identity's role set.</summary>