From bb75bbbe7c17a38d7cfc5ebb65325d2352bc4b89 Mon Sep 17 00:00:00 2001
From: Ponchanon Datta Rone <ponchanon.rone@gmail.com>
Date: Wed, 12 Aug 2026 09:48:46 -0500
Subject: [PATCH] feat(authorization): add permission evaluator

---
 Directory.Packages.props                      |  4 +
 OpenHealthOS.slnx                             |  4 +
 .../Authorization/PermissionEvaluator.cs      | 33 +++++++
 .../Authorization/PermissionEvaluatorTests.cs | 87 +++++++++++++++++++
 tests/UnitTests/OpenHealthOS.UnitTests.csproj | 19 ++++
 5 files changed, 147 insertions(+)
 create mode 100644 src/BuildingBlocks/Security/Authorization/PermissionEvaluator.cs
 create mode 100644 tests/UnitTests/Authorization/PermissionEvaluatorTests.cs
 create mode 100644 tests/UnitTests/OpenHealthOS.UnitTests.csproj

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 9287ced..46e12a9 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -36,6 +36,10 @@
 
     <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
 
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+
   </ItemGroup>
 
 </Project>
\ No newline at end of file
diff --git a/OpenHealthOS.slnx b/OpenHealthOS.slnx
index 00fa214..b8bf438 100644
--- a/OpenHealthOS.slnx
+++ b/OpenHealthOS.slnx
@@ -28,4 +28,8 @@
   <Folder Name="/src/Gateway/">
     <Project Path="src/Gateway/OpenHealthOS.Gateway.csproj" />
   </Folder>
+  <Folder Name="/tests/" />
+  <Folder Name="/tests/UnitTests/">
+    <Project Path="tests/UnitTests/OpenHealthOS.UnitTests.csproj" />
+  </Folder>
 </Solution>
diff --git a/src/BuildingBlocks/Security/Authorization/PermissionEvaluator.cs b/src/BuildingBlocks/Security/Authorization/PermissionEvaluator.cs
new file mode 100644
index 0000000..2e583e0
--- /dev/null
+++ b/src/BuildingBlocks/Security/Authorization/PermissionEvaluator.cs
@@ -0,0 +1,33 @@
+namespace OpenHealthOS.Security.Authorization;
+
+using OpenHealthOS.Contracts.Authorization;
+
+/// <summary>
+/// Evaluates authorization permissions using the scopes
+/// associated with the authenticated identity.
+/// </summary>
+public sealed class PermissionEvaluator : IAuthorizationEvaluator
+{
+    /// <summary>
+    /// Evaluates whether the requested permission is granted.
+    /// </summary>
+    /// <param name="context">
+    /// The authorization context to evaluate.
+    /// </param>
+    /// <returns>
+    /// <see cref="AuthorizationDecision.Allow"/> when the permission is
+    /// granted; otherwise <see cref="AuthorizationDecision.Deny"/>.
+    /// </returns>
+    public AuthorizationDecision Evaluate(AuthorizationContextDto context)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        var permission = context.Permission.Value;
+
+        return context.Identity.Scopes.Contains(
+            permission,
+            StringComparer.OrdinalIgnoreCase)
+            ? AuthorizationDecision.Allow
+            : AuthorizationDecision.Deny;
+    }
+}
diff --git a/tests/UnitTests/Authorization/PermissionEvaluatorTests.cs b/tests/UnitTests/Authorization/PermissionEvaluatorTests.cs
new file mode 100644
index 0000000..43a2212
--- /dev/null
+++ b/tests/UnitTests/Authorization/PermissionEvaluatorTests.cs
@@ -0,0 +1,87 @@
+namespace OpenHealthOS.UnitTests.Authorization;
+
+using OpenHealthOS.Contracts.Authorization;
+using OpenHealthOS.Contracts.Identity;
+using OpenHealthOS.Security.Authorization;
+using Xunit;
+
+public sealed class PermissionEvaluatorTests
+{
+    private readonly PermissionEvaluator _evaluator = new();
+
+    [Fact]
+    public void Evaluate_ShouldThrow_WhenContextIsNull()
+    {
+        var action = () => { _evaluator.Evaluate(null!); };
+
+        Assert.Throws<ArgumentNullException>(action);
+    }
+
+    [Fact]
+    public void Evaluate_ShouldAllow_WhenPermissionExistsInScopes()
+    {
+        var context = CreateContext(
+            scopes: ["patient.read"]);
+
+        var result = _evaluator.Evaluate(context);
+
+        Assert.Equal(
+            AuthorizationDecision.Allow,
+            result);
+    }
+
+    [Fact]
+    public void Evaluate_ShouldDeny_WhenPermissionIsNotGranted()
+    {
+        var context = CreateContext(
+            scopes: ["patient.write"]);
+
+        var result = _evaluator.Evaluate(context);
+
+        Assert.Equal(
+            AuthorizationDecision.Deny,
+            result);
+    }
+
+    [Fact]
+    public void Evaluate_ShouldDeny_WhenIdentityHasNoPermissions()
+    {
+        var context = CreateContext();
+
+        var result = _evaluator.Evaluate(context);
+
+        Assert.Equal(
+            AuthorizationDecision.Deny,
+            result);
+    }
+
+    [Fact]
+    public void Evaluate_ShouldBeCaseInsensitive()
+    {
+        var context = CreateContext(
+            scopes: ["PATIENT.READ"]);
+
+        var result = _evaluator.Evaluate(context);
+
+        Assert.Equal(
+            AuthorizationDecision.Allow,
+            result);
+    }
+
+    private static AuthorizationContextDto CreateContext(
+    IReadOnlyCollection<string>? scopes = null)
+    {
+        return new AuthorizationContextDto
+        {
+            Identity = new IdentityContextDto
+            {
+                SubjectId = "test-user",
+                PrincipalType = PrincipalType.User,
+                Scopes = scopes ?? Array.Empty<string>(),
+                Roles = Array.Empty<string>(),
+            },
+            Permission = new Permission("patient.read"),
+            ResourceType = "Patient",
+        };
+    }
+}
diff --git a/tests/UnitTests/OpenHealthOS.UnitTests.csproj b/tests/UnitTests/OpenHealthOS.UnitTests.csproj
new file mode 100644
index 0000000..3297996
--- /dev/null
+++ b/tests/UnitTests/OpenHealthOS.UnitTests.csproj
@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\BuildingBlocks\Security\OpenHealthOS.Security.csproj" />
+  </ItemGroup>
+
+</Project>