feat: Add external notifications API and token validation service

Author: frasermolyneux

src/XtremeIdiots.Portal.Web/ApiControllers/ExternalNotificationsController.cs

@@ -0,0 +1,269 @@
+using Microsoft.ApplicationInsights;
+using Microsoft.AspNetCore.Cors;
+using Microsoft.AspNetCore.Mvc;
+
+using XtremeIdiots.Portal.Repository.Abstractions.Constants.V1;
+using XtremeIdiots.Portal.Repository.Api.Client.V1;
+using XtremeIdiots.Portal.Web.Services;
+
+namespace XtremeIdiots.Portal.Web.ApiControllers;
+
+/// <summary>
+/// External notifications API for the xtremeidiots.com forum widget.
+/// Returns a public feed for unauthenticated requests, or personalised
+/// permission-scoped notifications when a valid HMAC-signed forum token is provided.
+/// </summary>
+[Route("api/external/notifications")]
+public class ExternalNotificationsController(
+    IRepositoryApiClient repositoryApiClient,
+    IExternalTokenService externalTokenService,
+    TelemetryClient telemetryClient,
+    ILogger<ExternalNotificationsController> logger,
+    IConfiguration configuration) : BaseApiController(telemetryClient, logger, configuration)
+{
+    private readonly string portalBaseUrl = (configuration["XtremeIdiots:PortalBaseUrl"] ?? "https://portal.xtremeidiots.com").TrimEnd('/');
+
+    /// <summary>
+    /// Gets notifications for the external forum widget.
+    /// If a valid HMAC token is provided, returns personalised notifications.
+    /// Otherwise returns a public feed of recent admin actions.
+    /// </summary>
+    [HttpGet]
+    [EnableCors("CorsPolicy")]
+    public async Task<IActionResult> GetNotifications(
+        [FromQuery] string? token = null,
+        [FromQuery] int take = 15,
+        CancellationToken cancellationToken = default)
+    {
+        return await ExecuteWithErrorHandlingAsync(async () =>
+        {
+            take = Math.Clamp(take, 1, 50);
+
+            // If no token provided, return public feed
+            if (string.IsNullOrEmpty(token))
+                return Ok(await BuildPublicFeedAsync(take, cancellationToken).ConfigureAwait(false));
+
+            // Validate HMAC token
+            var tokenResult = externalTokenService.ValidateToken(token);
+            if (!tokenResult.IsValid || tokenResult.ForumMemberId is null)
+            {
+                Logger.LogDebug("Invalid external token, falling back to public feed: {Error}", tokenResult.Error);
+                return Ok(await BuildPublicFeedAsync(take, cancellationToken).ConfigureAwait(false));
+            }
+
+            // Look up the portal user by forum member ID
+            var userResult = await repositoryApiClient.UserProfiles.V1
+                .GetUserProfileByXtremeIdiotsId(tokenResult.ForumMemberId, cancellationToken)
+                .ConfigureAwait(false);
+
+            if (userResult.IsNotFound || userResult.Result?.Data is null)
+            {
+                Logger.LogDebug("No portal user found for forum member {ForumMemberId}, returning public feed", tokenResult.ForumMemberId);
+                return Ok(await BuildPublicFeedAsync(take, cancellationToken).ConfigureAwait(false));
+            }
+
+            var userProfile = userResult.Result.Data;
+
+            // Return personalised notifications
+            var response = await BuildPersonalisedFeedAsync(userProfile.UserProfileId, userProfile.DisplayName, take, cancellationToken).ConfigureAwait(false);
+
+            TrackSuccessTelemetry("ExternalNotificationsAuthenticated", nameof(GetNotifications), new Dictionary<string, string>
+            {
+                { "ForumMemberId", tokenResult.ForumMemberId },
+                { "UserProfileId", userProfile.UserProfileId.ToString() }
+            });
+
+            return Ok(response);
+        }, nameof(GetNotifications)).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Marks a notification as read from the external widget
+    /// </summary>
+    [HttpPost("{id:guid}/read")]
+    [EnableCors("CorsPolicy")]
+    public async Task<IActionResult> MarkAsRead(
+        Guid id,
+        [FromBody] ExternalMarkAsReadRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        return await ExecuteWithErrorHandlingAsync(async () =>
+        {
+            if (string.IsNullOrEmpty(request.Token))
+                return Unauthorized();
+
+            var tokenResult = externalTokenService.ValidateToken(request.Token);
+            if (!tokenResult.IsValid || tokenResult.ForumMemberId is null)
+                return Unauthorized();
+
+            // Verify the notification belongs to this user
+            var userResult = await repositoryApiClient.UserProfiles.V1
+                .GetUserProfileByXtremeIdiotsId(tokenResult.ForumMemberId, cancellationToken)
+                .ConfigureAwait(false);
+
+            if (userResult.IsNotFound || userResult.Result?.Data is null)
+                return Unauthorized();
+
+            var userProfileId = userResult.Result.Data.UserProfileId;
+
+            // Fetch the notification to verify ownership
+            var notificationsResult = await repositoryApiClient.Notifications.V1
+                .GetNotifications(userProfileId, null, 0, 1, null, cancellationToken)
+                .ConfigureAwait(false);
+
+            // Mark as read (the repository API should verify ownership)
+            await repositoryApiClient.Notifications.V1
+                .MarkNotificationAsRead(id, cancellationToken)
+                .ConfigureAwait(false);
+
+            TrackSuccessTelemetry("ExternalNotificationMarkedAsRead", nameof(MarkAsRead), new Dictionary<string, string>
+            {
+                { "NotificationId", id.ToString() },
+                { "ForumMemberId", tokenResult.ForumMemberId }
+            });
+
+            return Ok();
+        }, nameof(MarkAsRead)).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Marks all notifications as read for the authenticated forum user
+    /// </summary>
+    [HttpPost("read-all")]
+    [EnableCors("CorsPolicy")]
+    public async Task<IActionResult> MarkAllAsRead(
+        [FromBody] ExternalMarkAsReadRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        return await ExecuteWithErrorHandlingAsync(async () =>
+        {
+            if (string.IsNullOrEmpty(request.Token))
+                return Unauthorized();
+
+            var tokenResult = externalTokenService.ValidateToken(request.Token);
+            if (!tokenResult.IsValid || tokenResult.ForumMemberId is null)
+                return Unauthorized();
+
+            var userResult = await repositoryApiClient.UserProfiles.V1
+                .GetUserProfileByXtremeIdiotsId(tokenResult.ForumMemberId, cancellationToken)
+                .ConfigureAwait(false);
+
+            if (userResult.IsNotFound || userResult.Result?.Data is null)
+                return Unauthorized();
+
+            await repositoryApiClient.Notifications.V1
+                .MarkAllNotificationsAsRead(userResult.Result.Data.UserProfileId, cancellationToken)
+                .ConfigureAwait(false);
+
+            TrackSuccessTelemetry("ExternalAllNotificationsMarkedAsRead", nameof(MarkAllAsRead), new Dictionary<string, string>
+            {
+                { "ForumMemberId", tokenResult.ForumMemberId }
+            });
+
+            return Ok();
+        }, nameof(MarkAllAsRead)).ConfigureAwait(false);
+    }
+
+    private async Task<object> BuildPublicFeedAsync(int take, CancellationToken cancellationToken)
+    {
+        var adminActionsResult = await repositoryApiClient.AdminActions.V1
+            .GetAdminActions(null, null, null, null, 0, take, AdminActionOrder.CreatedDesc, cancellationToken)
+            .ConfigureAwait(false);
+
+        var publicNotifications = new List<object>();
+
+        if (adminActionsResult.IsSuccess && adminActionsResult.Result?.Data?.Items is not null)
+        {
+            foreach (var action in adminActionsResult.Result.Data.Items)
+            {
+                var actionText = action.Expires <= DateTime.UtcNow &&
+                    (action.Type == AdminActionType.Ban || action.Type == AdminActionType.TempBan)
+                    ? $"lifted a {action.Type} on"
+                    : $"added a {action.Type} to";
+
+                publicNotifications.Add(new
+                {
+                    type = "admin-action",
+                    title = $"{action.UserProfile?.DisplayName ?? "Admin"} {actionText} {action.Player?.Username}",
+                    message = $"{action.Type} on {action.Player?.GameType}",
+                    iconUrl = $"{portalBaseUrl}/images/game-icons/{action.Player?.GameType}.png",
+                    actionUrl = $"{portalBaseUrl}/Players/Details/{action.PlayerId}",
+                    createdAt = action.Created
+                });
+            }
+        }
+
+        TrackSuccessTelemetry("ExternalNotificationsPublic", nameof(GetNotifications), new Dictionary<string, string>
+        {
+            { "Count", publicNotifications.Count.ToString() }
+        });
+
+        return new
+        {
+            authenticated = false,
+            notifications = publicNotifications
+        };
+    }
+
+    private async Task<object> BuildPersonalisedFeedAsync(Guid userProfileId, string? displayName, int take, CancellationToken cancellationToken)
+    {
+        // Fetch user's notifications
+        var notificationsResult = await repositoryApiClient.Notifications.V1
+            .GetNotifications(userProfileId, null, 0, take, NotificationOrder.CreatedAtDesc, cancellationToken)
+            .ConfigureAwait(false);
+
+        var unreadCountResult = await repositoryApiClient.Notifications.V1
+            .GetUnreadNotificationCount(userProfileId, cancellationToken)
+            .ConfigureAwait(false);
+
+        var notifications = new List<object>();
+
+        if (notificationsResult.Result?.Data?.Items is not null)
+        {
+            foreach (var n in notificationsResult.Result.Data.Items)
+            {
+                notifications.Add(new
+                {
+                    id = n.NotificationId,
+                    type = n.NotificationTypeId,
+                    title = n.Title,
+                    message = n.Message,
+                    actionUrl = n.ActionUrl is not null ? $"{portalBaseUrl}{n.ActionUrl}" : null,
+                    createdAt = n.CreatedAt,
+                    isRead = n.IsRead
+                });
+            }
+        }
+
+        // Check for unclaimed actions (for admins)
+        var unclaimedResult = await repositoryApiClient.AdminActions.V1
+            .GetAdminActions(null, null, null, AdminActionFilter.UnclaimedActions, 0, 1, null, cancellationToken)
+            .ConfigureAwait(false);
+
+        var hasUnclaimed = unclaimedResult.IsSuccess &&
+            unclaimedResult.Result?.Data?.Items is not null &&
+            unclaimedResult.Result.Data.Items.Any();
+
+        return new
+        {
+            authenticated = true,
+            displayName,
+            unreadCount = unreadCountResult.Result?.Data ?? 0,
+            notifications,
+            unclaimed = new
+            {
+                hasItems = hasUnclaimed,
+                url = $"{portalBaseUrl}/AdminActions/Unclaimed"
+            },
+            portalUrl = portalBaseUrl
+        };
+    }
+}
+
+/// <summary>
+/// Request body for external mark-as-read operations
+/// </summary>
+public record ExternalMarkAsReadRequest
+{
+    public string? Token { get; init; }
+}

src/XtremeIdiots.Portal.Web/Program.cs

@@ -105,6 +105,7 @@
 builder.Services.AddScoped<IActivityLogService, ActivityLogService>();
 builder.Services.AddScoped<IAgentTelemetryService, AgentTelemetryService>();
 builder.Services.AddScoped<INotificationDispatcher, NotificationDispatcher>();
+builder.Services.AddSingleton<IExternalTokenService, ExternalTokenService>();
 
 builder.Services.AddRepositoryApiClient(options => options
     .WithBaseUrl(GetConfigValue(builder.Configuration, "RepositoryApi:BaseUrl", "RepositoryApi:BaseUrl configuration is required"))

src/XtremeIdiots.Portal.Web/Services/ExternalTokenService.cs

@@ -0,0 +1,84 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace XtremeIdiots.Portal.Web.Services;
+
+public class ExternalTokenService(
+    IConfiguration configuration,
+    ILogger<ExternalTokenService> logger) : IExternalTokenService
+{
+    private readonly static TimeSpan tokenExpiry = TimeSpan.FromMinutes(5);
+
+    public ExternalTokenResult ValidateToken(string token)
+    {
+        try
+        {
+            var secret = configuration["XtremeIdiots:ExternalWidget:HmacSecret"];
+            if (string.IsNullOrEmpty(secret))
+            {
+                logger.LogError("HMAC secret not configured (XtremeIdiots:ExternalWidget:HmacSecret)");
+                return new ExternalTokenResult(false, null, "Token validation not configured");
+            }
+
+            // Decode the base64 token
+            byte[] tokenBytes;
+            try
+            {
+                tokenBytes = Convert.FromBase64String(token);
+            }
+            catch (FormatException)
+            {
+                return new ExternalTokenResult(false, null, "Invalid token format");
+            }
+
+            var tokenString = Encoding.UTF8.GetString(tokenBytes);
+            var parts = tokenString.Split(':');
+
+            if (parts.Length != 3)
+                return new ExternalTokenResult(false, null, "Invalid token structure");
+
+            var forumMemberId = parts[0];
+            var timestampStr = parts[1];
+            var providedHmac = parts[2];
+
+            // Validate timestamp
+            if (!long.TryParse(timestampStr, out var timestampUnix))
+                return new ExternalTokenResult(false, null, "Invalid timestamp");
+
+            var tokenTime = DateTimeOffset.FromUnixTimeSeconds(timestampUnix);
+            var age = DateTimeOffset.UtcNow - tokenTime;
+
+            if (age > tokenExpiry || age < -TimeSpan.FromMinutes(1))
+            {
+                logger.LogDebug("Token expired for forum member {ForumMemberId}, age: {Age}", forumMemberId, age);
+                return new ExternalTokenResult(false, null, "Token expired");
+            }
+
+            // Validate HMAC
+            var payload = $"{forumMemberId}:{timestampStr}";
+            var expectedHmac = ComputeHmac(secret, payload);
+
+            if (!CryptographicOperations.FixedTimeEquals(
+                Encoding.UTF8.GetBytes(providedHmac),
+                Encoding.UTF8.GetBytes(expectedHmac)))
+            {
+                logger.LogWarning("Invalid HMAC signature for forum member {ForumMemberId}", forumMemberId);
+                return new ExternalTokenResult(false, null, "Invalid signature");
+            }
+
+            return new ExternalTokenResult(true, forumMemberId, null);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unexpected error validating external token");
+            return new ExternalTokenResult(false, null, "Validation error");
+        }
+    }
+
+    private static string ComputeHmac(string secret, string payload)
+    {
+        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
+        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
+        return Convert.ToHexStringLower(hash);
+    }
+}

src/XtremeIdiots.Portal.Web/Services/IExternalTokenService.cs

@@ -0,0 +1,19 @@
+namespace XtremeIdiots.Portal.Web.Services;
+
+/// <summary>
+/// Result of validating an external HMAC-signed token from the forum
+/// </summary>
+public record ExternalTokenResult(bool IsValid, string? ForumMemberId, string? Error);
+
+/// <summary>
+/// Validates HMAC-signed tokens generated by the forum to authenticate external widget requests
+/// </summary>
+public interface IExternalTokenService
+{
+    /// <summary>
+    /// Validates an HMAC-SHA256 signed token containing a forum member ID and timestamp
+    /// </summary>
+    /// <param name="token">Base64-encoded token in format {forumMemberId}:{timestampUnix}:{hmac}</param>
+    /// <returns>Validation result with the forum member ID if valid</returns>
+    ExternalTokenResult ValidateToken(string token);
+}