From 3348f3d71d56fbe0dff8a9abf3e5f4934a05bdfe Mon Sep 17 00:00:00 2001
From: Ponchanon Datta Rone <ponchanon.rone@gmail.com>
Date: Mon, 10 Aug 2026 23:48:06 -0500
Subject: [PATCH] feat(contracts): add authorization contracts

---
 .../Authorization/AuthorizationContextDto.cs  | 39 +++++++++++++++++++
 .../Authorization/AuthorizationDecision.cs    | 17 ++++++++
 .../Contracts/Authorization/Permission.cs     | 34 ++++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 src/BuildingBlocks/Contracts/Authorization/AuthorizationContextDto.cs
 create mode 100644 src/BuildingBlocks/Contracts/Authorization/AuthorizationDecision.cs
 create mode 100644 src/BuildingBlocks/Contracts/Authorization/Permission.cs

diff --git a/src/BuildingBlocks/Contracts/Authorization/AuthorizationContextDto.cs b/src/BuildingBlocks/Contracts/Authorization/AuthorizationContextDto.cs
new file mode 100644
index 0000000..cc7046c
--- /dev/null
+++ b/src/BuildingBlocks/Contracts/Authorization/AuthorizationContextDto.cs
@@ -0,0 +1,39 @@
+namespace OpenHealthOS.Contracts.Authorization;
+
+using OpenHealthOS.Contracts.Identity;
+
+/// <summary>
+/// Represents the information required to evaluate an authorization request.
+/// </summary>
+public sealed record AuthorizationContextDto
+{
+    /// <summary>
+    /// Gets the authenticated identity associated with the request.
+    /// </summary>
+    public required IdentityContextDto Identity { get; init; }
+
+    /// <summary>
+    /// Gets the permission being requested.
+    /// </summary>
+    public required Permission Permission { get; init; }
+
+    /// <summary>
+    /// Gets the resource type against which authorization is evaluated.
+    /// </summary>
+    public required string ResourceType { get; init; }
+
+    /// <summary>
+    /// Gets the optional resource identifier.
+    /// </summary>
+    public string? ResourceId { get; init; }
+
+    /// <summary>
+    /// Gets the optional tenant identifier associated with the resource.
+    /// </summary>
+    public string? TenantId { get; init; }
+
+    /// <summary>
+    /// Gets the optional organization identifier associated with the resource.
+    /// </summary>
+    public string? OrganizationId { get; init; }
+}
diff --git a/src/BuildingBlocks/Contracts/Authorization/AuthorizationDecision.cs b/src/BuildingBlocks/Contracts/Authorization/AuthorizationDecision.cs
new file mode 100644
index 0000000..d8b046a
--- /dev/null
+++ b/src/BuildingBlocks/Contracts/Authorization/AuthorizationDecision.cs
@@ -0,0 +1,17 @@
+namespace OpenHealthOS.Contracts.Authorization;
+
+/// <summary>
+/// Represents the outcome of an authorization evaluation.
+/// </summary>
+public enum AuthorizationDecision
+{
+    /// <summary>
+    /// Access is allowed.
+    /// </summary>
+    Allow = 1,
+
+    /// <summary>
+    /// Access is denied.
+    /// </summary>
+    Deny = 2,
+}
diff --git a/src/BuildingBlocks/Contracts/Authorization/Permission.cs b/src/BuildingBlocks/Contracts/Authorization/Permission.cs
new file mode 100644
index 0000000..3ad6bb1
--- /dev/null
+++ b/src/BuildingBlocks/Contracts/Authorization/Permission.cs
@@ -0,0 +1,34 @@
+namespace OpenHealthOS.Contracts.Authorization;
+
+/// <summary>
+/// Represents a named authorization permission.
+/// </summary>
+public sealed record Permission
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Permission"/> class.
+    /// </summary>
+    /// <param name="value">The stable permission identifier.</param>
+    public Permission(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            throw new ArgumentException(
+                "Permission value cannot be null or whitespace.",
+                nameof(value));
+        }
+
+        Value = value;
+    }
+
+    /// <summary>
+    /// Gets the stable permission identifier.
+    /// </summary>
+    public string Value { get; }
+
+    /// <summary>
+    /// Returns the permission identifier.
+    /// </summary>
+    /// <returns>The permission identifier string.</returns>
+    public override string ToString() => Value;
+}