feat: complete task board workflow gates

backend/Services/RequestAuthorizationHelper.cs

@@ -0,0 +1,50 @@
+using Microsoft.Extensions.Primitives;
+
+namespace Nexus.Api.Services;
+
+public static class RequestAuthorizationHelper
+{
+    public sealed record AgentHeaderResolution(string? AgentId, bool HeaderProvided, bool IsRecognized);
+
+    public static bool IsAuthenticatedService(HttpContext httpContext, IConfiguration configuration) =>
+        httpContext.User.IsInRole("Service") || HasValidServiceKey(httpContext, configuration);
+
+    public static bool IsPrivilegedUser(HttpContext httpContext) =>
+        httpContext.User.Identity?.IsAuthenticated == true &&
+        (httpContext.User.IsInRole("owner") || httpContext.User.IsInRole("admin"));
+
+    public static async Task<string?> ResolveAllowedAgentHeaderAsync(
+        HttpContext httpContext,
+        IAgentService agentService,
+        CancellationToken ct)
+        => (await ResolveAgentHeaderAsync(httpContext, agentService, ct)).AgentId;
+
+    public static async Task<AgentHeaderResolution> ResolveAgentHeaderAsync(
+        HttpContext httpContext,
+        IAgentService agentService,
+        CancellationToken ct)
+    {
+        var headerValue = httpContext.Request.Headers["X-Agent-Id"].FirstOrDefault();
+        if (string.IsNullOrWhiteSpace(headerValue))
+            return new AgentHeaderResolution(null, HeaderProvided: false, IsRecognized: false);
+
+        var allowed = AgentIdentityCatalog.BuildAllowedActorIds(await agentService.GetAllowedAgentIdsAsync(ct));
+        var normalized = AgentIdentityCatalog.NormalizeActorId(headerValue, allowed);
+        return new AgentHeaderResolution(
+            normalized,
+            HeaderProvided: true,
+            IsRecognized: normalized is not null);
+    }
+
+    public static bool HasValidServiceKey(HttpContext httpContext, IConfiguration configuration)
+    {
+        var configuredApiKey = configuration["NexusApiKey"];
+        if (string.IsNullOrWhiteSpace(configuredApiKey))
+            return false;
+
+        if (!httpContext.Request.Headers.TryGetValue("X-Nexus-Api-Key", out StringValues providedKey))
+            return false;
+
+        return string.Equals(configuredApiKey, providedKey.FirstOrDefault(), StringComparison.Ordinal);
+    }
+}