From 9ec8f3c2d081496d13be596b1411d247f00cf841 Mon Sep 17 00:00:00 2001
From: Theaux Masquelier <43664045+Theauxm@users.noreply.github.com>
Date: Tue, 3 Mar 2026 14:33:47 -0700
Subject: [PATCH] feat: add [TraxAuthorize] attribute for per-train
 authorization

Adds TraxAuthorizeAttribute with Policy and Roles properties.
Trains decorated with this attribute have their authorization
requirements checked before execution via the API layer.
---
 .../Attributes/TraxAuthorizeAttribute.cs      | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 src/Trax.Effect/Attributes/TraxAuthorizeAttribute.cs

diff --git a/src/Trax.Effect/Attributes/TraxAuthorizeAttribute.cs b/src/Trax.Effect/Attributes/TraxAuthorizeAttribute.cs
new file mode 100644
index 0000000..0a491a3
--- /dev/null
+++ b/src/Trax.Effect/Attributes/TraxAuthorizeAttribute.cs
@@ -0,0 +1,37 @@
+namespace Trax.Effect.Attributes;
+
+/// <summary>
+/// Specifies authorization requirements for a train when executed via the Trax API.
+/// </summary>
+/// <remarks>
+/// When a train is executed through the REST or GraphQL API, the framework checks
+/// for this attribute and enforces the specified authorization requirements against
+/// the current HTTP user before allowing execution.
+///
+/// Trains without this attribute have no per-train authorization requirements
+/// (though endpoint-level auth from the <c>configure</c> callback still applies).
+///
+/// Multiple attributes can be combined — all must be satisfied.
+/// The scheduler bypasses this check entirely since it is trusted infrastructure.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
+public class TraxAuthorizeAttribute : Attribute
+{
+    /// <summary>
+    /// The name of an ASP.NET Core authorization policy that must be satisfied.
+    /// </summary>
+    public string? Policy { get; init; }
+
+    /// <summary>
+    /// A comma-separated list of roles. The user must have at least one of these roles.
+    /// </summary>
+    public string? Roles { get; init; }
+
+    public TraxAuthorizeAttribute() { }
+
+    /// <summary>
+    /// Creates a new <see cref="TraxAuthorizeAttribute"/> requiring the specified policy.
+    /// </summary>
+    /// <param name="policy">The authorization policy name.</param>
+    public TraxAuthorizeAttribute(string policy) => Policy = policy;
+}