feat(dotnet-agent-identity): add the authority library

.github/workflows/ci.yml

@@ -1353,6 +1353,14 @@ jobs:
         run: ./crates/agent-channel-proto/dotnet/build.ps1
         shell: pwsh
 
+      - name: Agent identity tests
+        run: dotnet test dotnet/AgentIdentity/AgentIdentity.sln
+        shell: pwsh
+
+      - name: Build agent identity package
+        run: ./dotnet/AgentIdentity/build.ps1
+        shell: pwsh
+
   agent-identity-vectors:
     name: Agent Identity test vectors
     runs-on: ubuntu-latest

.github/workflows/publish-libraries.yml

@@ -40,7 +40,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        library: [ dotnet-client, dotnet-subscriber, utils, pedm-dotnet-client, agent-channel ]
+        library: [ dotnet-client, dotnet-subscriber, utils, pedm-dotnet-client, agent-channel, agent-identity ]
         include:
           - library: dotnet-client
             libpath: ./devolutions-gateway/openapi/dotnet-client
@@ -52,6 +52,8 @@ jobs:
             libpath: ./crates/devolutions-pedm/openapi/dotnet-client
           - library: agent-channel
             libpath: ./crates/agent-channel-proto/dotnet
+          - library: agent-identity
+            libpath: ./dotnet/AgentIdentity
 
     steps:
       - name: Check out ${{ github.repository }}

dotnet/AgentIdentity/AgentIdentity.sln

@@ -0,0 +1,28 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Devolutions.AgentIdentity", "Devolutions.AgentIdentity\Devolutions.AgentIdentity.csproj", "{A1DC1136-5E93-4B2C-8147-1008ECD4204B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Devolutions.AgentIdentity.Tests", "Devolutions.AgentIdentity.Tests\Devolutions.AgentIdentity.Tests.csproj", "{60CED46A-EE0C-4C84-82BA-60DE4D518EC4}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{A1DC1136-5E93-4B2C-8147-1008ECD4204B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A1DC1136-5E93-4B2C-8147-1008ECD4204B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A1DC1136-5E93-4B2C-8147-1008ECD4204B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A1DC1136-5E93-4B2C-8147-1008ECD4204B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{60CED46A-EE0C-4C84-82BA-60DE4D518EC4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{60CED46A-EE0C-4C84-82BA-60DE4D518EC4}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{60CED46A-EE0C-4C84-82BA-60DE4D518EC4}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{60CED46A-EE0C-4C84-82BA-60DE4D518EC4}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+EndGlobal

dotnet/AgentIdentity/Devolutions.AgentIdentity.Tests/Authentication/AuthenticationTypeTests.cs

@@ -0,0 +1,105 @@
+using System.Reflection;
+
+namespace Devolutions.AgentIdentity.Tests;
+
+/// <summary>
+/// The types that only request authentication, the channel handshake and the enrollment rules create.
+/// </summary>
+/// <remarks>
+/// INTENT.md: code that acts for an identity takes it as a type only the signature check can create,
+/// so that an identity is never taken from a value the agent or a caller sent.
+/// </remarks>
+public class AuthenticationTypeTests
+{
+    private static readonly Type[] AuthenticationTypes =
+    [
+        // oracle: intent dotnet/AgentIdentity/INTENT.md §Authenticated identity
+        typeof(AuthenticatedIdentity),
+        // The handshake turns an opening into an identity,
+        // so an opening built by a caller would yield an identity that no signature check produced.
+        // oracle: intent dotnet/AgentIdentity/INTENT.md §Authenticated identity
+        typeof(ChannelOpening),
+        // A new identity's certificate is issued from the decision that creates it,
+        // so a decision built by a caller would certify a key for an identity that no enrollment created.
+        // oracle: intent dotnet/AgentIdentity/INTENT.md §Authenticated identity
+        typeof(EnrollmentDecision),
+        // oracle: mutant a public AuthenticationResult constructor
+        typeof(AuthenticationResult),
+        // oracle: mutant a public ChannelOpeningResult constructor
+        typeof(ChannelOpeningResult),
+        // oracle: mutant a public ChannelHandshakeResult constructor
+        typeof(ChannelHandshakeResult),
+    ];
+
+    public static TheoryData<Type> AuthenticationTypeData => new(AuthenticationTypes);
+
+    // Code that acts for an identity takes it as a type only the signature check can create.
+    // A public or protected constructor would let a caller build an identity from any values,
+    // or a subclass of one with its own constructor.
+    // The other types carry an identity, the opening that becomes one, or the decision that creates one,
+    // out of a check.
+    // Each row's marker names what decides it.
+    // oracle: intent dotnet/AgentIdentity/INTENT.md §Authenticated identity
+    [Theory]
+    [MemberData(nameof(AuthenticationTypeData))]
+    public void TypeHasNoPublicOrProtectedConstructor(Type type)
+    {
+        IEnumerable<ConstructorInfo> reachable = type
+            .GetConstructors(BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static)
+            .Where(IsReachableFromAnotherAssembly);
+
+        Assert.Empty(reachable);
+    }
+
+    // A new public member producing one of these types could be a factory that bypasses the check that creates it.
+    // The intent forbids creating an identity outside that check but not forwarding one that it created,
+    // so the list of members allowed to produce one is the library's own.
+    // oracle: mutant a public member that builds an AuthenticatedIdentity outside the signature check,
+    // or an EnrollmentDecision outside the enrollment rules
+    [Fact]
+    public void NoOtherPublicMemberProducesTheseTypes()
+    {
+        const BindingFlags declared = BindingFlags.Public | BindingFlags.NonPublic
+            | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly;
+
+        IEnumerable<string> producers = typeof(RequestAuthenticator).Assembly
+            .GetExportedTypes()
+            .SelectMany(type => type.GetMethods(declared)
+                .Where(IsReachableFromAnotherAssembly)
+                .Where(method => Produces(method.ReturnType))
+                .Select(method => $"{type.Name}.{method.Name}")
+                .Concat(type.GetFields(declared)
+                    .Where(field => field.IsPublic || field.IsFamily || field.IsFamilyOrAssembly)
+                    .Where(field => Produces(field.FieldType))
+                    .Select(field => $"{type.Name}.{field.Name}")));
+
+        Assert.Equal(
+            [
+                "AuthenticationResult.get_Identity",
+                "ChannelHandshakeResult.get_Identity",
+                "ChannelOpening.FirstMessageUnreadableAsync",
+                "ChannelOpening.HelloTimedOutAsync",
+                "ChannelOpening.VerifyHelloAsync",
+                "ChannelOpeningResult.get_Opening",
+                "EnrollmentRules.Decide",
+                "RequestAuthenticator.AuthenticateAsync",
+                "RequestAuthenticator.AuthenticateChannelOpeningAsync",
+            ],
+            producers.Order(StringComparer.Ordinal));
+    }
+
+    private static bool IsReachableFromAnotherAssembly(MethodBase method)
+    {
+        return method.IsPublic || method.IsFamily || method.IsFamilyOrAssembly;
+    }
+
+    private static bool Produces(Type type)
+    {
+        Type? definition = type.IsGenericType ? type.GetGenericTypeDefinition() : null;
+        Type produced = definition == typeof(ValueTask<>) || definition == typeof(Task<>)
+            ? type.GetGenericArguments()[0]
+            : type;
+
+        return AuthenticationTypes.Contains(produced);
+    }
+}

dotnet/AgentIdentity/Devolutions.AgentIdentity.Tests/Authentication/RegisteredCertificateTests.cs

@@ -0,0 +1,23 @@
+namespace Devolutions.AgentIdentity.Tests;
+
+public class RegisteredCertificateTests
+{
+    // An undefined status from the host's storage must fail as a host bug,
+    // rather than draw identity_unknown, which ends the identity for the agent.
+    // The default is the value of an uninitialized status, and 4 follows the last of the three statuses.
+    // CONTRACT.agent-identity.md Definitions: a certificate is pending, current or retired;
+    // §5.4: identity_unknown is terminal.
+    // Framework Design Guidelines, Parameter Design: validate enum parameters, since an enum may hold any integer.
+    // oracle: spec Framework Design Guidelines §Validating Arguments
+    // oracle: spec Framework Design Guidelines §Using Standard Exception Types
+    [Theory]
+    [InlineData(default(CertificateStatus))]
+    [InlineData((CertificateStatus)4)]
+    public void RefusesAnUndefinedStatus(CertificateStatus undefined)
+    {
+        KeyVector key = TestVectors.Instance.Key("device-a");
+
+        Assert.Throws<ArgumentOutOfRangeException>(
+            () => new RegisteredCertificate(key.IdentityId, key.Certificate, undefined, identityRevoked: false));
+    }
+}