Refactor auth, docs, and add best practices

Refactored `AuthAttribute` and introduced `JwtAuthAttribute` for improved authentication handling. Added `JWTOrApiKeyAuthenticationMiddleware` and `ApiKeyOrJwtAuthorizeAttribute` to support dual authentication modes (API key and JWT).

Enhanced documentation:
- Added folder structure and infrastructure setup details in `README.md`.
- Introduced best practices for .NET Core in `cloud_architect.mdc`.
- Added new modes for code reviewers and documentation writers.

Updated `manual.yml` to remove redundancy and improve formatting.

Author: GioemaNocco

.cursor/rules/cloud_architect.mdc

@@ -0,0 +1,88 @@
+---
+description: This rule provides comprehensive best practices for developing dotnet applications, covering code organization, security, performance, testing, and common pitfalls. It aims to improve code quality, security posture, and overall efficiency when working with the .NET Core framework.
+globs: *.tf,*.bicep,*.json,*.yml,*.yaml,*.cs,*.csproj,*.sln
+alwaysApply: false
+---
+
+# .NET Core Library Best Practices and Coding Standards
+
+This document outlines the recommended best practices for developing applications and infrastructure using Microsoft .NET Core, Azure DevOps and Azure services. It covers various aspects including solution setup, code organization, security, and tooling to ensure robust, scalable, and secure solutions.
+
+## 1. Code Organization and Structure
+
+A well-organized codebase is crucial for maintainability, scalability, and collaboration. The following guidelines provide a structured approach to organizing your .NET projects.
+
+### Directory Structure Best Practices
+
+Adopt a modular and logical directory structure based on the application's architecture and components.
+
+*   **`devops/`**: Contains the root folder for DevOps pipelines for your application.
+    *   **`azure/`**: Contains the source code of Azure DevOps pipelines for your application.
+*   **`infrastructure/`**: Contains the source code of IaC and platform setup scripts for your application.
+    *   **`bicep/`**: Contains the source code of Bicep templates for your application.
+    *   **`terraform/`**: Contains the source code of Terraform templates for your application.
+*   **`scripts/`**: Automation scripts for deployment, build processes, etc.
+*   **`src/`**: Contains the source code of your application.
+
+
+Example:
+
+root-project/
+├── .cursor/
+│   └── rules/
+├── .git/
+├── .github/
+│   ├── chatmode
+│   ├── instructions
+│   └── workflows/
+├── devops/
+│   └── azure/
+├── infrastructure/
+│   ├── bicep/
+│   └── terraform/
+├── scripts/
+├── src/
+├── .editorconfig
+├── .gitattributes
+├── .gitignore
+├── CHANGELOG.md
+├── CODE_OF_CONDUCT.md
+├── Directory.Build.props
+├── Directory.Build.targets
+├── dotnet.ruleset
+├── global.json
+├── stylecop.json
+├── nuget.config
+├── project.sln
+└── README.md
+
+
+### File Naming Conventions
+
+Maintain consistency in file naming to improve readability and searchability.
+
+*   Use descriptive names that reflect the file's purpose.
+*   Use a consistent case (e.g., camelCase or kebab-case).
+*   Use appropriate file extensions (e.g., `.cs`, `.csproj`, `.tf`, `.bicep`).
+*   For CSharp components, use `ClassName.cs` or `ComponentName.SubComponent.cs`.
+
+Example:
+
+*   `user-service.js` (for a user service module)
+*   `UserProfile.jsx` (for a user profile component)
+*   `storage-account.tf` (for a Terraform file defining a storage account)
+
+### Module Organization
+
+Divide the application into independent and reusable modules based on functionality.
+
+*   Each module should have a clear responsibility and a well-defined interface.
+*   Minimize dependencies between modules to promote loose coupling.
+*   Consider using a module bundler (e.g., Webpack, Parcel) to manage dependencies and optimize the build process.
+
+Example:
+
+A `user-management` module could contain components and services related to user authentication, authorization, and profile management.
+
+
+By following these best practices, you can build robust, scalable, secure, and maintainable .NET applications.

.github/chatmodes/Code Reviewer.chatmode.md

@@ -0,0 +1,27 @@
+---
+description: 'Review code for quality and adherence to best practices.'
+tools: ['codebase', 'usages', 'vscodeAPI', 'problems', 'fetch', 'githubRepo', 'search']
+---
+
+# Code Reviewer Mode
+You are an experienced senior developer conducting a thorough code review. Your role is to review the code for quality, best practices, and adherence to [project standards](../copilot-instructions.md) without making direct code changes.
+
+## Analysis Focus
+- Analyze code quality, structure, and best practices
+- Identify potential bugs, security issues, or performance problems
+- Evaluate accessibility and user experience considerations
+- Assess maintainability and readability
+
+## Communication Style
+- Provide constructive, specific feedback with clear explanations
+- Highlight both strengths and areas for improvement
+- Ask clarifying questions about design decisions when appropriate
+- Suggest alternative approaches when relevant
+
+## Important Guidelines
+- DO NOT write or suggest specific code changes directly
+- Focus on explaining what should be changed and why
+- Provide reasoning behind your recommendations
+- Be encouraging while maintaining high standards
+
+When reviewing code, structure your feedback with clear headings and specific examples from the code being reviewed.

.github/chatmodes/Documentation Writer.chatmode.md

@@ -0,0 +1,21 @@
+---
+description: 'Document code and its functionality.'
+tools: ['search']
+---
+
+# Documentation Writer Mode
+You are a Documentation Writer. Your task is to create clear, concise, and comprehensive documentation for codebases, APIs, libraries, and software projects. You should focus on explaining complex technical concepts in an accessible manner, ensuring that the documentation is useful for both novice and experienced developers.
+
+## Documentation Focus
+- Write clear and concise explanations of code functionality
+- Include usage examples and code snippets where applicable
+- Document any dependencies, configurations, or setup steps required
+- Ensure that the documentation is kept up-to-date with code changes
+
+## Communication Style
+- Use simple, straightforward language
+- Break down complex concepts into manageable sections
+- Use bullet points, numbered lists, and headings to organize information
+- Provide context and background information when necessary
+- Write WebAPI endpoint documentation to be used by MCP server and AI agent along with developers
+- Write the web API endpoint documentation in the OpenAPI format, with short summaries and descriptions for each endpoint, including request and response schemas.

.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+---
+applyTo: '**'
+---
+
+You are a cloud solution architect. Your role is to design and oversee the implementation of microservice application based on .NET Core. Your responsibilities include selecting appropriate pattern and best practice, ensuring security and compliance, optimizing perfomrance and stability.
+Your expertise in cloud platforms such as Azure, along with your knowledge of networking, security, and DevOps practices, will be crucial in delivering scalable and reliable solutions delivered on cloud.

.github/instructions/solution_architect.md

@@ -0,0 +1,5 @@
+---
+applyTo: '**'
+---
+You are a cloud solution architect. Your role is to design and oversee the implementation of microservice application based on .NET Core. Your responsibilities include selecting appropriate pattern and best practice, ensuring security and compliance, optimizing perfomrance and stability.
+Your expertise in cloud platforms such as Azure, along with your knowledge of networking, security, and DevOps practices, will be crucial in delivering scalable and reliable solutions delivered on cloud.

.github/workflows/manual.yml

@@ -44,4 +44,4 @@ jobs:
         run: echo ${{ github.run_number }}
 
       - name: Output Run Attempt
-        run: echo ${{ github.run_attempt }}        
+        run: echo ${{ github.run_attempt }}

README.md

@@ -64,6 +64,65 @@ You can find a useful documentation about how to use the library. The documentat
 
 Documentation available at [Genocs Blog](https://genocs-blog.netlify.app/library/)
 
+
+## Folders structure
+
+```text
+## Repository structure for .NET Solution
+
+root-project/
+├── .cursor/
+│   ├── rules/
+│   │   └── ...
+├── .git/
+│   └── ...
+├── .github/
+│   ├── chatmodes
+│   │   ├── Code Reviewer.chatmode.md
+│   │   ├── Documentation Writer.chatmode.md
+│   │   └── ...
+│   ├── copilot-instructions.md
+│   ├── workflows/
+│   │   ├── ...
+├── devops/
+│   ├── azure
+│   │   ├── ci-publish_on_acr.yml
+│   │   ├── ci-publish_on_nuget.yml
+│   │   └── ...
+├── infrastructure/
+│   ├── bicep/
+│   │   └── ...
+│   ├── docker-compose/
+│   │   └── ...
+│   ├── k8s/
+│   │   └── ...
+│   ├── terraform/
+│   │   └── ...
+│   ├── ...
+├── scripts/
+│   └── ...
+├── src/
+│   └── ...
+├── .dockerignore
+├── .editconfig
+├── .env
+├── .gitattributes
+├── .gitignore
+├── Directory.Build.props
+├── Directory.Build.targets
+├── dotnet.ruleset
+├── global.json
+├── icon.png
+├── stylecop.json
+├── nuget.config
+├── [project].sln
+├── README.md
+├── LICENSE
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── api-workbench.rest
+└── ...
+
 ## Infrastructure
 
 In this section you can find the infrastructure components you need to execute the solution. Infrastucture components are the database, the enterprice servise bus, the distributed logging, monitoring, tracing systems along with database and many more.

src/Genocs.Auth/Attributes/ApiKeyOrJwtAuthorizeAttribute.cs

@@ -0,0 +1,39 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+
+namespace Genocs.Auth.Attributes;
+
+/// <summary>
+/// Authorization attribute that allows access with either valid JWT token or valid API key.
+/// </summary>
+/// <remarks>
+/// This attribute enables dual authentication modes for endpoints:
+/// 1. Standard JWT Bearer token authentication
+/// 2. API key authentication via x-gnx-apikey header
+/// Used primarily for system-to-system communication endpoints that need to support both authentication methods.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+public class ApiKeyOrJwtAuthorizeAttribute : Attribute, IAuthorizationFilter
+{
+    public void OnAuthorization(AuthorizationFilterContext context)
+    {
+        // Check if user is authenticated via any method
+        if (context.HttpContext.User.Identity?.IsAuthenticated == true)
+        {
+            return; // Allow access
+        }
+
+        // Check for API key in header
+        string? apiKey = context.HttpContext.Request.Headers["x-gnx-apikey"];
+        if (!string.IsNullOrEmpty(apiKey))
+        {
+            // API key validation is handled in middleware
+            // If we reach here with an API key, it means middleware didn't authenticate
+            context.Result = new UnauthorizedObjectResult("Invalid API key");
+            return;
+        }
+
+        // No valid authentication found
+        context.Result = new UnauthorizedObjectResult("Authentication required. Provide either Bearer token or apikey.");
+    }
+}

src/Genocs.Auth/AuthAttribute.cs renamed to src/Genocs.Auth/Attributes/AuthAttribute.cs

@@ -1,6 +1,6 @@
 using Microsoft.AspNetCore.Authorization;
 
-namespace Genocs.Auth;
+namespace Genocs.Auth.Attributes;
 
 /// <summary>
 /// The authorization Attribute.

src/Genocs.Auth/FirebaseAuthenticationMiddleware.cs

@@ -0,0 +1,105 @@
+using System.IdentityModel.Tokens.Jwt;
+using System.Security.Claims;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Configuration;
+using Microsoft.IdentityModel.Tokens;
+
+namespace Genocs.Auth;
+
+/// <summary>
+/// Middleware for handling JWT authentication and API key authentication.
+/// </summary>
+/// <remarks>
+/// This middleware supports dual authentication modes:
+/// 1. API Key authentication via x-gnx-apikey header for system-to-system communication
+/// 2. JWT Bearer token authentication for user authentication
+/// When API key is provided, it bypasses JWT validation and sets up API key-based claims.
+/// </remarks>
+public class JWTOrApiKeyAuthenticationMiddleware(RequestDelegate next, IConfiguration configuration)
+{
+    private readonly RequestDelegate _next = next;
+    private readonly IConfiguration _configuration = configuration;
+
+    public async Task Invoke(HttpContext context)
+    {
+        // Check for API key authentication first
+        string? apiKey = context.Request.Headers["x-gnx-apikey"];
+        if (!string.IsNullOrEmpty(apiKey))
+        {
+            if (await ValidateApiKeyAsync(apiKey))
+            {
+                // Set up API key-based authentication
+                var claims = new[]
+                {
+                    new Claim(ClaimTypes.NameIdentifier, "api-client"),
+                    new Claim(ClaimTypes.Name, "API Client"),
+                    new Claim("auth_type", "apikey"),
+                    new Claim("api_key", apiKey)
+                };
+
+                var identity = new ClaimsIdentity(claims, "ApiKey");
+                context.User = new ClaimsPrincipal(identity);
+
+                await _next(context);
+                return;
+            }
+            else
+            {
+                // Invalid API key
+                context.Response.StatusCode = 401;
+                await context.Response.WriteAsync("Invalid API key");
+                return;
+            }
+        }
+
+        // Check for Firebase JWT authentication
+        string? authHeader = context.Request.Headers.Authorization;
+        if (authHeader?.StartsWith("Bearer ") == true)
+        {
+            string token = authHeader["Bearer ".Length..].Trim();
+
+            try
+            {
+                var handler = new JwtSecurityTokenHandler();
+                var jsonToken = handler.ReadToken(token) as JwtSecurityToken ?? throw new SecurityTokenException("Invalid token format");
+                var payload = jsonToken.Payload;
+                var claims = new[]
+                {
+                    new Claim(ClaimTypes.NameIdentifier, payload["user_id"]?.ToString() ?? string.Empty),
+                    new Claim(ClaimTypes.Name, payload["name"]?.ToString() ?? string.Empty),
+                    new Claim("auth_type", "jwt")
+
+                    // Add more claims as needed
+                };
+
+                var identity = new ClaimsIdentity(claims, "AuthenticationTypes.Federation");
+                context.User = new ClaimsPrincipal(identity);
+            }
+            catch (Exception)
+            {
+                // Token validation failed - but don't return error here
+                // Let the authorization attributes handle it
+            }
+        }
+
+        await _next(context);
+    }
+
+    /// <summary>
+    /// Validates the provided API key against configured valid keys.
+    /// </summary>
+    /// <param name="apiKey">The API key to validate.</param>
+    /// <returns>True if the API key is valid, false otherwise.</returns>
+    private async Task<bool> ValidateApiKeyAsync(string apiKey)
+    {
+        // Get valid API keys from configuration
+        string[] validApiKeys = _configuration.GetSection("Authentication:ApiKeys").Get<string[]>() ?? [];
+
+        // For development/testing
+        string? devApiKey = _configuration["Authentication:DevApiKey"];
+
+        bool isOk = validApiKeys.Contains(apiKey) || (!string.IsNullOrWhiteSpace(devApiKey) && devApiKey == apiKey);
+
+        return await Task.FromResult(isOk);
+    }
+}