feat(opcuaclient-browser): real AttributesAsync + certificate-auth browse (R06:O-5)

- AttributesAsync was a stub returning nothing; it now reads NodeClass / DisplayName / DataType / ValueRank / UserAccessLevel in one request and maps them through UpstreamAttributeMapping, the same mapping discovery registers with (moved into the shared .Session leaf; the driver forwards to it). Objects have no value attributes. - Certificate auth was refused "in v1". The browse now builds its identity through OpcUaUserIdentityFactory (shared .Session leaf, the driver forwards to it), including the secret: resolution of Password / UserCertificatePassword through the host's ISecretResolver (optional ctor param, DI-injected). Fail-closed: a secret: ref with no store throws instead of being sent as the literal (the browse used to send a secret: Password verbatim). The identity is built before any network I/O. Refs #743 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 15:33:08 -04:00
parent d98f4a5bf1
commit fcdc44f9f7
11 changed files with 492 additions and 134 deletions
@@ -0,0 +1,115 @@
+using Opc.Ua;
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
+
+/// <summary>
+///     The ONE place the OpcUaClient user identity is built from <see cref="OpcUaClientDriverOptions"/> — shared by
+///     the runtime driver's session open and the AdminUI live browse, so a certificate-authenticated upstream is
+///     browsable with exactly the credentials the deployed driver will present. Includes the <c>secret:</c>
+///     resolution of the two credential fields (fail-closed).
+/// </summary>
+public static class OpcUaUserIdentityFactory
+{
+    private const string SecretPrefix = "secret:";
+
+    /// <summary>
+    ///     Build the user-identity token from options whose credential fields are already resolved plaintext
+    ///     (see <see cref="ResolveSecretRefsAsync"/>).
+    /// </summary>
+    /// <param name="options">Driver options containing authentication configuration.</param>
+    /// <returns>The constructed <see cref="UserIdentity"/> for session activation.</returns>
+    public static UserIdentity Build(OpcUaClientDriverOptions options) =>
+        options.AuthType switch
+        {
+            OpcUaAuthType.Anonymous => new UserIdentity(new AnonymousIdentityToken()),
+            OpcUaAuthType.Username => new UserIdentity(
+                options.Username ?? string.Empty,
+                System.Text.Encoding.UTF8.GetBytes(options.Password ?? string.Empty)),
+            OpcUaAuthType.Certificate => FromCertificate(options),
+            _ => new UserIdentity(new AnonymousIdentityToken()),
+        };
+
+    /// <summary>
+    ///     Build a <see cref="UserIdentity"/> carrying a client user-authentication certificate loaded from
+    ///     <see cref="OpcUaClientDriverOptions.UserCertificatePath"/>. Fails fast if the path is missing, the file
+    ///     doesn't exist, or the certificate lacks a private key (required to sign the user-token challenge).
+    /// </summary>
+    /// <param name="options">Driver options containing certificate configuration.</param>
+    /// <returns>The certificate-backed <see cref="UserIdentity"/>.</returns>
+    public static UserIdentity FromCertificate(OpcUaClientDriverOptions options)
+    {
+        if (string.IsNullOrWhiteSpace(options.UserCertificatePath))
+            throw new InvalidOperationException(
+                "OpcUaAuthType.Certificate requires OpcUaClientDriverOptions.UserCertificatePath to be set.");
+        if (!File.Exists(options.UserCertificatePath))
+            throw new FileNotFoundException(
+                $"User certificate not found at '{options.UserCertificatePath}'.",
+                options.UserCertificatePath);
+
+        // X509CertificateLoader (new in .NET 9) is the only non-obsolete way to load a PFX
+        // since the legacy X509Certificate2 ctors are marked obsolete on net10.
+        var cert = System.Security.Cryptography.X509Certificates.X509CertificateLoader
+            .LoadPkcs12FromFile(options.UserCertificatePath, options.UserCertificatePassword);
+
+        if (!cert.HasPrivateKey)
+            throw new InvalidOperationException(
+                $"User certificate at '{options.UserCertificatePath}' has no private key — " +
+                "the private key is required to sign the OPC UA user-token challenge at session activation.");
+
+        return new UserIdentity(cert);
+    }
+
+    /// <summary>
+    ///     Return a copy of <paramref name="options"/> with any <c>secret:</c>-prefixed
+    ///     <see cref="OpcUaClientDriverOptions.Password"/> / <see cref="OpcUaClientDriverOptions.UserCertificatePassword"/>
+    ///     resolved through <paramref name="resolver"/>. Non-secret / null / empty fields pass through unchanged (the
+    ///     reference-equal original is returned when nothing changed). Fail-closed: an absent secret, or a
+    ///     <c>secret:</c> ref with no resolver available, throws rather than sending the literal as a credential.
+    /// </summary>
+    /// <param name="options">The raw options (credential fields may carry <c>secret:</c> refs).</param>
+    /// <param name="resolver">The shared secret resolver, or null when none is available.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>An options copy whose credential fields carry resolved plaintext.</returns>
+    public static async Task<OpcUaClientDriverOptions> ResolveSecretRefsAsync(
+        OpcUaClientDriverOptions options, ISecretResolver? resolver, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        var password = await ResolveFieldAsync(options.Password, nameof(options.Password), resolver, ct)
+            .ConfigureAwait(false);
+        var certPassword = await ResolveFieldAsync(
+            options.UserCertificatePassword, nameof(options.UserCertificatePassword), resolver, ct)
+            .ConfigureAwait(false);
+
+        if (ReferenceEquals(password, options.Password)
+            && ReferenceEquals(certPassword, options.UserCertificatePassword))
+        {
+            return options;
+        }
+
+        return options with { Password = password, UserCertificatePassword = certPassword };
+    }
+
+    private static async Task<string?> ResolveFieldAsync(
+        string? value, string fieldName, ISecretResolver? resolver, CancellationToken ct)
+    {
+        if (string.IsNullOrEmpty(value)
+            || !value.StartsWith(SecretPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return value;
+        }
+
+        var name = value[SecretPrefix.Length..];
+        if (resolver is null)
+            throw new InvalidOperationException(
+                $"OpcUaClientDriverOptions.{fieldName}='{value}' references secret '{name}', but no secret store is " +
+                "available here (fail-closed).");
+        var resolved = await resolver.GetAsync(new SecretName(name), ct).ConfigureAwait(false);
+        return !string.IsNullOrEmpty(resolved)
+            ? resolved
+            : throw new InvalidOperationException(
+                $"OpcUaClientDriverOptions.{fieldName}='{value}' resolves secret '{name}', but it is " +
+                "absent from the store (fail-closed).");
+    }
+}
@@ -0,0 +1,65 @@
+using Opc.Ua;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
+
+/// <summary>
+///     The ONE mapping from an upstream variable's OPC UA attributes (DataType, ValueRank, AccessLevel) to the
+///     driver-agnostic shape — shared by the runtime driver's discovery enrichment and the AdminUI live browse
+///     side-panel, so the picker shows exactly what a browse-commit / discovery would register.
+/// </summary>
+public static class UpstreamAttributeMapping
+{
+    /// <summary>
+    ///     Map an upstream OPC UA built-in DataType NodeId (via <c>DataTypeIds.*</c>) to a
+    ///     <see cref="DriverDataType"/>. Unknown / custom types fall through to
+    ///     <see cref="DriverDataType.String"/> which is the safest passthrough for
+    ///     Variant-wrapped structs + enums + extension objects.
+    /// </summary>
+    /// <param name="dataType">The OPC UA data type NodeId to map.</param>
+    /// <returns>The mapped <see cref="DriverDataType"/>.</returns>
+    public static DriverDataType MapDataType(NodeId dataType)
+    {
+        if (dataType == DataTypeIds.Boolean) return DriverDataType.Boolean;
+        // SByte (signed 8-bit) shares Int16 — DriverDataType has no narrower signed type.
+        // Byte (unsigned 8-bit) belongs in the unsigned family → UInt16, not Int16
+        // (mapping an unsigned 0-255 type onto Int16 misrepresents type metadata and
+        // confuses range/validation logic keyed off DriverDataType).
+        if (dataType == DataTypeIds.SByte || dataType == DataTypeIds.Int16) return DriverDataType.Int16;
+        if (dataType == DataTypeIds.Byte || dataType == DataTypeIds.UInt16) return DriverDataType.UInt16;
+        if (dataType == DataTypeIds.Int32) return DriverDataType.Int32;
+        if (dataType == DataTypeIds.UInt32) return DriverDataType.UInt32;
+        if (dataType == DataTypeIds.Int64) return DriverDataType.Int64;
+        if (dataType == DataTypeIds.UInt64) return DriverDataType.UInt64;
+        if (dataType == DataTypeIds.Float) return DriverDataType.Float32;
+        if (dataType == DataTypeIds.Double) return DriverDataType.Float64;
+        if (dataType == DataTypeIds.String) return DriverDataType.String;
+        if (dataType == DataTypeIds.DateTime || dataType == DataTypeIds.UtcTime)
+            return DriverDataType.DateTime;
+        return DriverDataType.String;
+    }
+
+    /// <summary>
+    ///     Map an OPC UA AccessLevel/UserAccessLevel attribute value (<c>AccessLevels</c> bitmask) to a
+    ///     <see cref="SecurityClassification"/>: CurrentWrite-capable variables surface as
+    ///     <see cref="SecurityClassification.Operate"/>; read-only as <see cref="SecurityClassification.ViewOnly"/>.
+    /// </summary>
+    /// <param name="accessLevel">The OPC UA access level bitmask.</param>
+    /// <returns>The mapped security classification.</returns>
+    public static SecurityClassification MapAccessLevel(byte accessLevel)
+    {
+        const byte CurrentWrite = 2; // AccessLevels.CurrentWrite = 0x02
+        return (accessLevel & CurrentWrite) != 0
+            ? SecurityClassification.Operate
+            : SecurityClassification.ViewOnly;
+    }
+
+    /// <summary>
+    ///     OPC UA Part 3 ValueRank: -3 ScalarOrOneDimension, -2 Any, -1 Scalar, 0 OneOrMoreDimensions, 1 OneDimension,
+    ///     &gt;1 N dimensions. Anything &gt;= 0 is an array; -3 / -2 are conservatively scalar until the upstream variable
+    ///     carries a concrete dimensioned rank.
+    /// </summary>
+    /// <param name="valueRank">The ValueRank attribute.</param>
+    /// <returns>Whether the variable is exposed as an array.</returns>
+    public static bool IsArray(int valueRank) => valueRank >= 0;
+}
@@ -11,8 +11,9 @@
    </PropertyGroup>
    <!--
        The live-OPC-UA-session layer of the OpcUaClient driver: everything the driver AND the AdminUI's
-        browser both need that is typed in ISession / NodeId / NamespaceTable. Today that is exactly
-        NamespaceMap.
+        browser both need that is typed in ISession / NodeId / NamespaceTable / UserIdentity: NamespaceMap,
+        UpstreamAttributeMapping (DataType/AccessLevel/ValueRank -> driver shape) and OpcUaUserIdentityFactory
+        (credential secret: resolution + the SDK UserIdentity, incl. certificate auth).

        WHY IT IS NOT IN .Contracts. It used to be, and .Contracts therefore carried
        OPCFoundation.NetStandard.Opc.Ua.Client. When G-7 wired OpcUaClientTagDefinitionFactory.Inspect into
@@ -35,6 +36,10 @@
    -->
    <ItemGroup>
        <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.Client" />
+        <!-- OpcUaUserIdentityFactory: the secret: resolution of the credential fields feeding the SDK UserIdentity is
+             shared by the driver and the AdminUI browse (review 2026-10-21 O-5), so the browse presents exactly the
+             credentials the deployed driver will. Abstractions only (one interface + a name type). -->
+        <PackageReference Include="ZB.MOM.WW.Secrets.Abstractions" />
    </ItemGroup>
    <ItemGroup>
        <!-- RawTagEntry (the v3 authored-tag identity NamespaceMap indexes) lives in the Core.Abstractions