Add S3 storage support with Terraform updates

Introduced Amazon S3 as a storage provider alongside local storage.
Added `S3StorageService` and `S3StorageOptions` for handling S3
operations, including file uploads, deletions, and public URL
generation. Updated dependency injection to dynamically select
storage provider based on configuration.

Enhanced Terraform scripts to provision an S3 bucket with optional
public read access and CloudFront distribution. Added resources for
bucket ownership enforcement, public access blocking, and CloudFront
origin access control. Introduced new variables for S3 configuration
and updated outputs for S3 bucket and CloudFront details.

Updated `appsettings.json` to include S3 configuration. Improved
security by enforcing bucket ownership and disabling ACLs. Updated
container images for API and Blazor services. Maintained backward
compatibility with local storage as the default provider.

Author: iammukeshm

src/BuildingBlocks/Storage/Extensions.cs

@@ -1,5 +1,9 @@
-using FSH.Framework.Storage.Local;
+using Amazon;
+using Amazon.S3;
+using FSH.Framework.Storage.Local;
+using FSH.Framework.Storage.S3;
 using FSH.Framework.Storage.Services;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 
 namespace FSH.Framework.Storage;
@@ -11,4 +15,39 @@ public static IServiceCollection AddHeroLocalFileStorage(this IServiceCollection
         services.AddScoped<IStorageService, LocalStorageService>();
         return services;
     }
+
+    public static IServiceCollection AddHeroStorage(this IServiceCollection services, IConfiguration configuration)
+    {
+        var provider = configuration["Storage:Provider"]?.ToLowerInvariant();
+
+        if (string.Equals(provider, "s3", StringComparison.OrdinalIgnoreCase))
+        {
+            services.Configure<S3StorageOptions>(configuration.GetSection("Storage:S3"));
+
+            services.AddSingleton<IAmazonS3>(sp =>
+            {
+                var options = sp.GetRequiredService<Microsoft.Extensions.Options.IOptions<S3StorageOptions>>().Value;
+
+                if (string.IsNullOrWhiteSpace(options.Bucket))
+                {
+                    throw new InvalidOperationException("Storage:S3:Bucket is required when using S3 storage.");
+                }
+
+                if (string.IsNullOrWhiteSpace(options.Region))
+                {
+                    return new AmazonS3Client();
+                }
+
+                return new AmazonS3Client(RegionEndpoint.GetBySystemName(options.Region));
+            });
+
+            services.AddTransient<IStorageService, S3StorageService>();
+        }
+        else
+        {
+            services.AddScoped<IStorageService, LocalStorageService>();
+        }
+
+        return services;
+    }
 }

src/BuildingBlocks/Storage/S3/S3StorageOptions.cs

@@ -0,0 +1,10 @@
+namespace FSH.Framework.Storage.S3;
+
+public sealed class S3StorageOptions
+{
+    public string? Bucket { get; set; }
+    public string? Region { get; set; }
+    public string? Prefix { get; set; }
+    public bool PublicRead { get; set; } = true;
+    public string? PublicBaseUrl { get; set; }
+}

src/BuildingBlocks/Storage/S3/S3StorageService.cs

@@ -0,0 +1,146 @@
+using Amazon.S3;
+using Amazon.S3.Model;
+using FSH.Framework.Storage.DTOs;
+using FSH.Framework.Storage.Services;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using System;
+using System.Text.RegularExpressions;
+
+namespace FSH.Framework.Storage.S3;
+
+internal sealed class S3StorageService : IStorageService
+{
+    private readonly IAmazonS3 _s3;
+    private readonly S3StorageOptions _options;
+    private readonly ILogger<S3StorageService> _logger;
+
+    private const string UploadBasePath = "uploads";
+
+    public S3StorageService(IAmazonS3 s3, IOptions<S3StorageOptions> options, ILogger<S3StorageService> logger)
+    {
+        _s3 = s3;
+        _options = options.Value ?? throw new ArgumentNullException(nameof(options));
+        _logger = logger;
+
+        if (string.IsNullOrWhiteSpace(_options.Bucket))
+        {
+            throw new InvalidOperationException("Storage:S3:Bucket is required when using S3 storage.");
+        }
+    }
+
+    public async Task<string> UploadAsync<T>(FileUploadRequest request, FileType fileType, CancellationToken cancellationToken = default) where T : class
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        var rules = FileTypeMetadata.GetRules(fileType);
+        var extension = Path.GetExtension(request.FileName);
+
+        if (string.IsNullOrWhiteSpace(extension) || !rules.AllowedExtensions.Contains(extension, StringComparer.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException($"File type '{extension}' is not allowed. Allowed: {string.Join(", ", rules.AllowedExtensions)}");
+        }
+
+        if (request.Data.Count > rules.MaxSizeInMB * 1024 * 1024)
+        {
+            throw new InvalidOperationException($"File exceeds max size of {rules.MaxSizeInMB} MB.");
+        }
+
+        var key = BuildKey<T>(SanitizeFileName(request.FileName));
+
+        using var stream = new MemoryStream(request.Data.Select(Convert.ToByte).ToArray());
+
+        var putRequest = new PutObjectRequest
+        {
+            BucketName = _options.Bucket,
+            Key = key,
+            InputStream = stream,
+            ContentType = request.ContentType
+        };
+
+        // Rely on bucket policy for public access; do not set ACLs to avoid conflicts with ACL-disabled buckets.
+        await _s3.PutObjectAsync(putRequest, cancellationToken).ConfigureAwait(false);
+        _logger.LogInformation("Uploaded file to S3 bucket {Bucket} with key {Key}", _options.Bucket, key);
+
+        return BuildPublicUrl(key);
+    }
+
+    public async Task RemoveAsync(string path, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return;
+        }
+
+        try
+        {
+            var key = NormalizeKey(path);
+            await _s3.DeleteObjectAsync(_options.Bucket, key, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to delete S3 object {Path}", path);
+        }
+    }
+
+    private string BuildKey<T>(string fileName) where T : class
+    {
+        var folder = Regex.Replace(typeof(T).Name.ToLowerInvariant(), @"[^a-z0-9]", "_");
+        var relativePath = Path.Combine(UploadBasePath, folder, $"{Guid.NewGuid():N}_{fileName}").Replace("\\", "/", StringComparison.Ordinal);
+        if (!string.IsNullOrWhiteSpace(_options.Prefix))
+        {
+            return $"{_options.Prefix.TrimEnd('/')}/{relativePath}";
+        }
+
+        return relativePath;
+    }
+
+    private string BuildPublicUrl(string key)
+    {
+        var safeKey = key.TrimStart('/');
+
+        if (!string.IsNullOrWhiteSpace(_options.PublicBaseUrl))
+        {
+            return $"{_options.PublicBaseUrl.TrimEnd('/')}/{safeKey}";
+        }
+
+        if (!_options.PublicRead)
+        {
+            return key;
+        }
+
+        if (string.IsNullOrWhiteSpace(_options.Region) || string.Equals(_options.Region, "us-east-1", StringComparison.OrdinalIgnoreCase))
+        {
+            return $"https://{_options.Bucket}.s3.amazonaws.com/{safeKey}";
+        }
+
+        return $"https://{_options.Bucket}.s3.{_options.Region}.amazonaws.com/{safeKey}";
+    }
+
+    private string NormalizeKey(string path)
+    {
+        // If a full URL was passed, strip host and query to get the object key.
+        if (Uri.TryCreate(path, UriKind.Absolute, out var uri))
+        {
+            path = uri.AbsolutePath;
+        }
+
+        var trimmed = path.TrimStart('/');
+        if (!string.IsNullOrWhiteSpace(_options.Prefix) && trimmed.StartsWith(_options.Prefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return trimmed;
+        }
+
+        if (!string.IsNullOrWhiteSpace(_options.Prefix))
+        {
+            return $"{_options.Prefix.TrimEnd('/')}/{trimmed}";
+        }
+
+        return trimmed;
+    }
+
+    private static string SanitizeFileName(string fileName)
+    {
+        return Regex.Replace(fileName, @"[^a-zA-Z0-9_\.-]", "_");
+    }
+}

src/BuildingBlocks/Storage/Storage.csproj

@@ -16,5 +16,9 @@
 	<ItemGroup>
 		<FrameworkReference Include="Microsoft.AspNetCore.App" />
 	</ItemGroup>
+
+	<ItemGroup>
+	  <PackageReference Include="AWSSDK.S3" />
+	</ItemGroup>
 
 </Project>

src/Directory.Packages.props

@@ -94,4 +94,7 @@
     <PackageVersion Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Components.Web" Version="10.0.0" />
   </ItemGroup>
-</Project>
+  <ItemGroup Label="AWS">
+    <PackageVersion Include="AWSSDK.S3" Version="3.7.405.0" />
+  </ItemGroup>
+</Project>

src/Modules/Identity/Modules.Identity/IdentityModule.cs

@@ -9,6 +9,7 @@
 using FSH.Framework.Persistence;
 using FSH.Framework.Storage.Local;
 using FSH.Framework.Storage.Services;
+using FSH.Framework.Storage;
 using FSH.Framework.Web.Modules;
 using FSH.Modules.Identity.Authorization;
 using FSH.Modules.Identity.Authorization.Jwt;
@@ -61,7 +62,7 @@ public void ConfigureServices(IHostApplicationBuilder builder)
         services.AddScoped(sp => (ICurrentUserInitializer)sp.GetRequiredService<ICurrentUser>());
         services.AddTransient<IUserService, UserService>();
         services.AddTransient<IRoleService, RoleService>();
-        services.AddTransient<IStorageService, LocalStorageService>();
+        services.AddHeroStorage(builder.Configuration);
         services.AddScoped<IIdentityService, IdentityService>();
         services.AddHeroDbContext<IdentityDbContext>();
         services.AddEventingCore(builder.Configuration);

src/Playground/Playground.Api/appsettings.json

@@ -134,5 +134,12 @@
   },
   "MultitenancyOptions": {
     "RunTenantMigrationsOnStartup": true
+  },
+  "Storage": {
+    "Provider": "s3",
+    "S3": {
+      "Bucket": "dev-fsh-app-bucket",
+      "PublicBaseUrl": "https://d1rafgenord1fg.cloudfront.net"
+    }
   }
 }

terraform/apps/playground/app_stack/main.tf

@@ -69,24 +69,28 @@ module "alb" {
 module "app_s3" {
   source = "../../../modules/s3_bucket"
 
-  name = var.app_s3_bucket_name
-  tags = local.common_tags
+  name                = var.app_s3_bucket_name
+  tags                = local.common_tags
+  enable_public_read  = var.app_s3_enable_public_read
+  public_read_prefix  = var.app_s3_public_read_prefix
+  enable_cloudfront   = var.app_s3_enable_cloudfront
+  cloudfront_price_class = var.app_s3_cloudfront_price_class
 }
 
 module "rds" {
   source = "../../../modules/rds_postgres"
 
-  name                       = "${var.environment}-${var.region}-postgres"
-  vpc_id                     = module.network.vpc_id
-  subnet_ids                 = module.network.private_subnet_ids
+  name       = "${var.environment}-${var.region}-postgres"
+  vpc_id     = module.network.vpc_id
+  subnet_ids = module.network.private_subnet_ids
   allowed_security_group_ids = [
     module.api_service.security_group_id,
     module.blazor_service.security_group_id,
   ]
-  db_name                    = var.db_name
-  username                   = var.db_username
-  password                   = var.db_password
-  tags                       = local.common_tags
+  db_name  = var.db_name
+  username = var.db_username
+  password = var.db_password
+  tags     = local.common_tags
 }
 
 locals {
@@ -96,14 +100,14 @@ locals {
 module "redis" {
   source = "../../../modules/elasticache_redis"
 
-  name                       = "${var.environment}-${var.region}-redis"
-  vpc_id                     = module.network.vpc_id
-  subnet_ids                 = module.network.private_subnet_ids
+  name       = "${var.environment}-${var.region}-redis"
+  vpc_id     = module.network.vpc_id
+  subnet_ids = module.network.private_subnet_ids
   allowed_security_group_ids = [
     module.api_service.security_group_id,
     module.blazor_service.security_group_id,
   ]
-  tags                       = local.common_tags
+  tags = local.common_tags
 }
 
 module "api_service" {
@@ -118,9 +122,9 @@ module "api_service" {
   memory          = var.api_memory
   desired_count   = var.api_desired_count
 
-  vpc_id          = module.network.vpc_id
-  vpc_cidr_block  = module.network.vpc_cidr_block
-  subnet_ids      = module.network.private_subnet_ids
+  vpc_id           = module.network.vpc_id
+  vpc_cidr_block   = module.network.vpc_cidr_block
+  subnet_ids       = module.network.private_subnet_ids
   assign_public_ip = false
 
   listener_arn           = module.alb.listener_arn
@@ -133,6 +137,12 @@ module "api_service" {
     ASPNETCORE_ENVIRONMENT            = local.aspnetcore_environment
     DatabaseOptions__ConnectionString = local.db_connection_string
     CachingOptions__Redis             = "${module.redis.primary_endpoint_address}:6379,ssl=True,abortConnect=False"
+    OriginOptions__OriginUrl          = "http://${module.alb.dns_name}"
+    CorsOptions__AllowedOrigins__0    = "http://${module.alb.dns_name}"
+    Storage__Provider                 = "s3"
+    Storage__S3__Bucket               = var.app_s3_bucket_name
+    Storage__S3__PublicRead           = false
+    Storage__S3__PublicBaseUrl        = module.app_s3.cloudfront_domain_name != "" ? "https://${module.app_s3.cloudfront_domain_name}" : ""
   }
 
   tags = local.common_tags
@@ -150,9 +160,9 @@ module "blazor_service" {
   memory          = var.blazor_memory
   desired_count   = var.blazor_desired_count
 
-  vpc_id          = module.network.vpc_id
-  vpc_cidr_block  = module.network.vpc_cidr_block
-  subnet_ids      = module.network.private_subnet_ids
+  vpc_id           = module.network.vpc_id
+  vpc_cidr_block   = module.network.vpc_cidr_block
+  subnet_ids       = module.network.private_subnet_ids
   assign_public_ip = false
 
   listener_arn           = module.alb.listener_arn
@@ -188,3 +198,11 @@ output "rds_endpoint" {
 output "redis_endpoint" {
   value = module.redis.primary_endpoint_address
 }
+
+output "s3_bucket_name" {
+  value = module.app_s3.bucket_name
+}
+
+output "s3_cloudfront_domain" {
+  value = module.app_s3.cloudfront_domain_name
+}