diff --git a/.github/skills/implement-auth0-authentication/SKILL.md b/.github/skills/implement-auth0-authentication/SKILL.md new file mode 100644 index 0000000..4d08184 --- /dev/null +++ b/.github/skills/implement-auth0-authentication/SKILL.md @@ -0,0 +1,293 @@ +--- +name: implement-auth0-authentication +description: 'Add Auth0 authentication and authorization to a Blazor Server or Blazor Web App with interactive server components. Includes role-based authorization, claims transformation, user profile page, and admin user management via Auth0 Management API. Prompts for Auth0 tenant credentials, client secrets, callback URLs, role claim namespace, and Management API M2M application. Use for implementing OAuth 2.0 OIDC login, role management, user administration, and secure Blazor authentication with Auth0.' +argument-hint: '[optional: path to Blazor project directory]' +--- + +# Implement Auth0 Authentication for Blazor + +Adds complete Auth0 authentication and authorization infrastructure to a Blazor Server or Blazor Web App with interactive server components, including role-based access control, a profile page, and optional admin user management. + +## When to Use + +- Adding Auth0 authentication to a new or existing Blazor Server or Blazor Web App +- Implementing OAuth 2.0 OIDC login/logout with Auth0 +- Setting up role-based authorization mapped from Auth0 claims +- Creating a user profile page that displays claims and roles +- Building admin pages that manage Auth0 users and roles via the Management API +- Migrating from local cookie-only auth to Auth0 OIDC +- Hardening login/logout flows with antiforgery and local-return-url validation + +## Prerequisites + +Before starting, ensure you have: + +1. **Auth0 Account**: Active Auth0 tenant +2. **Web Application Configured in Auth0**: + - Application Type: Regular Web Application + - Allowed Callback URLs configured (for example `https://localhost:5001/callback`) + - Allowed Logout URLs configured (for example `https://localhost:5001/`) + - Domain, Client ID, and Client Secret available +3. **Auth0 Management API M2M Application** (for admin user management features): + - Application Type: Machine to Machine + - Authorized for Auth0 Management API + - Scopes granted: `read:users`, `update:users`, `read:roles`, `read:users_app_metadata`, `update:users_app_metadata` + - Client ID, Client Secret, Domain, and Audience available +4. **Role Configuration in Auth0**: + - Roles created (for example `Admin`, `User`) + - Auth0 Action or Rule configured to add roles to the ID token with a custom namespace such as `https://yourapp.com/roles` + +## What This Skill Does + +1. **Gathers Auth0 configuration** from the user (see [Configuration Prompts](./references/configuration-prompts.md)) +2. **Adds or updates Auth0 packages**: + - `Auth0.AspNetCore.Authentication` + - `Auth0.ManagementApi` (if admin user management is requested) + - If the repo uses Central Package Management, update `Directory.Packages.props` instead of adding versions in individual project files +3. **Configures authentication** in `Program.cs` with `AddAuth0WebAppAuthentication` +4. **Creates Auth infrastructure**: + - `Auth/Auth0Options.cs` — configuration model + - `Auth/Auth0ClaimsTransformation.cs` — maps Auth0 roles to ASP.NET Core `ClaimTypes.Role` + - `Auth/AuthorizationRoles.cs` — role constants (`Admin`, `User`) + - `Auth/AuthorizationPolicies.cs` — policy constants (`AdminPolicy`, `UserPolicy`) +5. **Maps explicit login/logout endpoints**: + - `GET /account/login` validates the `returnUrl` before calling the Auth0 challenge + - `POST /account/logout` uses antiforgery and signs out of both Auth0 and the local cookie + - `/callback` remains handled by the Auth0 SDK +6. **Creates login/logout UI components**: + - `Components/Layout/LoginDisplay.razor` — login/logout buttons with user greeting + - `Components/Layout/LoginComponent.razor` — minimal login/logout form +7. **Creates a user profile page**: + - `Components/User/Profile.razor` — displays claims, roles, profile picture, and email +8. **Creates admin user management** (optional): + - `Features/Admin/Users/Auth0ManagementOptions.cs` + - `Features/Admin/Users/UserManagementExtensions.cs` + - `Features/Admin/Users/UserManagementService.cs` + - `Domain/Features/Admin/Abstractions/IUserManagementService.cs` + - `Domain/Features/Admin/Models/AdminUserSummary.cs` + - `Domain/Features/Admin/Models/RoleAssignment.cs` + - `Components/Pages/Admin/Users.razor` + - `Components/Admin/Users/EditUserRolesModal.razor` + - `Components/Admin/Users/UserListTable.razor` + - `Components/Admin/Users/RoleBadge.razor` + - `Components/Admin/Users/UserAuditLogPanel.razor` (optional) +9. **Configures `appsettings.json` placeholders and user secrets** for sensitive values +10. **Adds cascading authentication state, middleware, and verification guidance** + +## Procedure + +### Step 1: Gather Configuration + +Prompt the user for the required values before making changes. Use [Configuration Prompts](./references/configuration-prompts.md). + +**Auth0 Web Application (OIDC):** +- `Auth0:Domain` +- `Auth0:ClientId` +- `Auth0:ClientSecret` +- `Auth0:RoleClaimNamespace` + +**Auth0 Management API M2M Application (optional):** +- `Auth0Management:ClientId` +- `Auth0Management:ClientSecret` +- `Auth0Management:Domain` +- `Auth0Management:Audience` + +**Callback and Logout URLs:** +- Callback URL (for example `https://localhost:5001/callback`) +- Logout URL (for example `https://localhost:5001/`) + +**Feature Selection:** +- Whether to include admin user management pages +- Whether to create a user profile page + +### Step 2: Add the Required Packages + +If the repo does **not** use Central Package Management: + +```bash +dotnet add package Auth0.AspNetCore.Authentication +``` + +If admin user management is requested: + +```bash +dotnet add package Auth0.ManagementApi +``` + +If the repo **does** use Central Package Management, update `Directory.Packages.props` instead of setting package versions in project files. + +### Step 3: Create Auth Infrastructure + +Create the following files in the `Auth/` folder if they do not already exist: + +- `Auth/Auth0Options.cs` +- `Auth/Auth0ClaimsTransformation.cs` +- `Auth/AuthorizationRoles.cs` +- `Auth/AuthorizationPolicies.cs` + +See [Auth0 Implementation](./references/auth-implementation.md) for the current code patterns. + +### Step 4: Configure Authentication in Program.cs + +Add the Auth0 authentication configuration shown in [Program.cs Configuration](./references/program-configuration.md), including: + +- Cookie auth in `Testing` +- `AddAuth0WebAppAuthentication` for non-test environments +- `IClaimsTransformation` registration +- Authorization policy registration +- `AddCascadingAuthenticationState()` +- Explicit `UseAuthentication()`, `UseAuthorization()`, and `UseAntiforgery()` middleware + +### Step 5: Map Secure Login/Logout Endpoints + +Create the endpoint pattern documented in [Program.cs Configuration](./references/program-configuration.md): + +- `GET /account/login` accepts `returnUrl`, rejects non-local redirect targets, and challenges the Auth0 scheme +- `POST /account/logout` requires authorization, includes antiforgery, and signs out of both Auth0 and the cookie scheme +- In `Testing`, add a lightweight `/test/login` endpoint so E2E tests do not depend on Auth0 + +### Step 6: Create Login/Logout UI Components + +Use the secure UI patterns in [Auth0 Implementation](./references/auth-implementation.md): + +- `Components/Layout/LoginDisplay.razor` +- `Components/Layout/LoginComponent.razor` + +Prefer base-relative `returnUrl` values so they pass local-url validation. + +### Step 7: Create the User Profile Page + +If requested, add `Components/User/Profile.razor` using the example in [Auth0 Implementation](./references/auth-implementation.md). + +### Step 8: Create Admin User Management + +If admin user management was requested, create: + +- `Domain/Features/Admin/Abstractions/IUserManagementService.cs` +- `Domain/Features/Admin/Models/AdminUserSummary.cs` +- `Domain/Features/Admin/Models/RoleAssignment.cs` +- `Features/Admin/Users/Auth0ManagementOptions.cs` +- `Features/Admin/Users/UserManagementExtensions.cs` +- `Features/Admin/Users/UserManagementService.cs` +- Admin UI components under `Components/Pages/Admin/Users.razor` and `Components/Admin/Users/` + +The current reference implementation targets **Auth0.ManagementApi v8** and uses: + +- `IManagementApiClient` +- `ManagementClient` +- `ManagementClientOptions` +- `ClientCredentialsTokenProvider` +- `Auth0.ManagementApi.Users` request/response types + +See [Admin User Management](./references/admin-user-management.md). + +### Step 9: Configure appsettings and User Secrets + +Add placeholder configuration to `appsettings.json`: + +```json +{ + "Auth0": { + "Domain": "", + "ClientId": "", + "ClientSecret": "", + "RoleClaimNamespace": "" + }, + "Auth0Management": { + "ClientId": "", + "ClientSecret": "", + "Domain": "", + "Audience": "" + } +} +``` + +Store secrets with `dotnet user-secrets` during development. Use Azure Key Vault, environment variables, or another secure secret store in production. + +### Step 10: Verify the Integration + +1. Ensure `UseAuthentication()`, `UseAuthorization()`, and `UseAntiforgery()` are present in the middleware pipeline +2. Ensure `AddCascadingAuthenticationState()` is registered +3. Verify Auth0 callback and logout URLs match the deployed app URLs +4. Test login/logout flows +5. Verify role claims are mapped correctly on the profile page +6. If admin features are enabled, verify user list and role assignment flows + +## Post-Implementation Testing + +### Test Login Flow + +1. Navigate to the application +2. Click **Log in** and verify the app redirects to Auth0 Universal Login +3. Authenticate with Auth0 credentials +4. Verify the app returns to the requested local page +5. Verify the user name appears in navigation + +### Test Role Mapping + +1. Log in with a user that has roles assigned in Auth0 +2. Navigate to `/profile` +3. Verify roles appear under **Roles & Permissions** +4. Verify the standard role claim type contains the mapped roles + +### Test Authorization + +1. Log in with a non-admin user +2. Attempt to access `/admin/users` and verify access is denied +3. Log in with an admin user +4. Verify `/admin/users` loads successfully + +### Test Admin User Management + +1. Log in as an admin +2. Navigate to `/admin/users` +3. Verify the user list loads +4. Open the role editor for a user +5. Assign and remove roles +6. Verify changes persist in Auth0 + +## Troubleshooting + +### Roles Not Appearing + +- **Cause**: `Auth0:RoleClaimNamespace` does not match the namespace in the Auth0 Action or Rule +- **Fix**: Update `Auth0:RoleClaimNamespace` to match exactly +- **Fallback**: `Auth0ClaimsTransformation` also checks the standard `roles` claim and auto-detects namespaced claims ending in `/roles` + +### Login Redirects to the Wrong Page + +- **Cause**: The UI passed an absolute URL or another non-local redirect target +- **Fix**: Generate a base-relative `returnUrl` and keep the local-URL validation in the login endpoint + +### Management API Calls Fail + +- **Cause**: The M2M app is missing scopes or has the wrong audience/domain +- **Fix**: Re-check the Auth0 Management API authorization settings and the `Auth0Management` configuration section + +### 401 or Token Errors from the Management API + +- **Cause**: `ClientCredentialsTokenProvider` is misconfigured, the secret is wrong, or the audience/domain does not match the tenant +- **Fix**: Verify `AddUserManagement()` registers `ManagementClient` with the correct domain, client ID, client secret, and audience + +## Architecture Decisions + +1. **Role Claim Mapping**: Use `IClaimsTransformation` to map Auth0 role claims to `ClaimTypes.Role` so ASP.NET Core policies and `RequireRole()` work normally. +2. **Multi-Pass Role Detection**: Check the configured namespace first, then `roles`, then any namespaced claim ending in `/roles`. +3. **Auth0.ManagementApi v8**: Prefer `IManagementApiClient` plus `ClientCredentialsTokenProvider` over manual token-fetch code. +4. **Result-Based Error Handling**: Return `Result` or `Result` for expected failures instead of relying on exception-driven flow. +5. **Cache Strategy**: Cache role lookup data in `IMemoryCache` and user/list responses in `IDistributedCache` when those dependencies exist. +6. **Testing Mode**: Use cookie auth plus a testing-only login endpoint so E2E runs do not depend on Auth0. + +## References + +- [Auth0 ASP.NET Core SDK Documentation](https://auth0.com/docs/quickstart/webapp/aspnet-core) +- [Auth0 Management API Documentation](https://auth0.com/docs/api/management/v2) +- [Auth0 Actions (Custom Claims)](https://auth0.com/docs/customize/actions) +- [ASP.NET Core Authorization](https://learn.microsoft.com/aspnet/core/security/authorization/introduction) + +## Additional Files + +- [Configuration Prompts](./references/configuration-prompts.md) +- [Program.cs Configuration](./references/program-configuration.md) +- [Auth0 Implementation](./references/auth-implementation.md) +- [Admin User Management](./references/admin-user-management.md) diff --git a/.github/skills/implement-auth0-authentication/references/admin-user-management.md b/.github/skills/implement-auth0-authentication/references/admin-user-management.md new file mode 100644 index 0000000..6016fe0 --- /dev/null +++ b/.github/skills/implement-auth0-authentication/references/admin-user-management.md @@ -0,0 +1,415 @@ +# Admin User Management Implementation + +This reference documents the current Auth0 Management API pattern used by the app. It targets **Auth0.ManagementApi v8** and relies on the SDK's `ClientCredentialsTokenProvider` instead of hand-rolled token fetching. + +Replace `YourApp` with your web project's root namespace in the web-layer snippets below. + +## Overview + +The admin user management feature enables administrators to: + +- List Auth0 users +- Read a single user's summary information and assigned roles +- List available Auth0 roles +- Assign and remove roles by role name +- Drive admin UI components such as `Users.razor`, `EditUserRolesModal.razor`, and `UserListTable.razor` + +## Prerequisites + +1. **Auth0 Management API M2M Application** created in the Auth0 Dashboard +2. **Scopes granted**: `read:users`, `update:users`, `read:roles`, `read:users_app_metadata`, `update:users_app_metadata` +3. **Client ID, Client Secret, Domain, and Audience** from the M2M application +4. **Auth0.ManagementApi v8.x** referenced by the project + +## Domain Contracts + +### Domain/Features/Admin/Abstractions/IUserManagementService.cs + +```csharp +using Domain.Abstractions; +using Domain.Features.Admin.Models; + +namespace Domain.Features.Admin.Abstractions; + +public interface IUserManagementService +{ +Task>> ListUsersAsync( +int page, +int perPage, +CancellationToken ct); + +Task> GetUserByIdAsync( +string userId, +CancellationToken ct); + +Task> AssignRolesAsync( +string userId, +IEnumerable roleNames, +CancellationToken ct); + +Task> RemoveRolesAsync( +string userId, +IEnumerable roleNames, +CancellationToken ct); + +Task>> ListRolesAsync(CancellationToken ct); +} +``` + +### Domain/Features/Admin/Models/AdminUserSummary.cs + +```csharp +namespace Domain.Features.Admin.Models; + +public record AdminUserSummary +{ +public string UserId { get; init; } = string.Empty; +public string Email { get; init; } = string.Empty; +public string Name { get; init; } = string.Empty; +public string Picture { get; init; } = string.Empty; +public IReadOnlyList Roles { get; init; } = []; +public DateTimeOffset? LastLogin { get; init; } +public bool IsBlocked { get; init; } + +public static AdminUserSummary Empty => new(); +} +``` + +### Domain/Features/Admin/Models/RoleAssignment.cs + +```csharp +namespace Domain.Features.Admin.Models; + +public record RoleAssignment +{ +public string RoleId { get; init; } = string.Empty; +public string RoleName { get; init; } = string.Empty; +public string Description { get; init; } = string.Empty; +} +``` + +## Web Layer Implementation + +### Features/Admin/Users/Auth0ManagementOptions.cs + +```csharp +namespace YourApp.Features.Admin.Users; + +public sealed record Auth0ManagementOptions +{ +public const string SectionName = "Auth0Management"; + +public string ClientId { get; init; } = string.Empty; +public string ClientSecret { get; init; } = string.Empty; +public string Domain { get; init; } = string.Empty; +public string Audience { get; init; } = string.Empty; +} +``` + +### Features/Admin/Users/UserManagementExtensions.cs + +Register the SDK client once, then consume `IManagementApiClient` from the scoped service. + +```csharp +using Auth0.ManagementApi; +using Domain.Features.Admin.Abstractions; +using Microsoft.Extensions.Options; + +namespace YourApp.Features.Admin.Users; + +public static class UserManagementExtensions +{ +public static IServiceCollection AddUserManagement( +this IServiceCollection services, +IConfiguration configuration) +{ +services.AddMemoryCache(); +services.Configure( +configuration.GetSection(Auth0ManagementOptions.SectionName)); + +services.AddSingleton(sp => +{ +var opts = sp.GetRequiredService>().Value; +var audience = string.IsNullOrWhiteSpace(opts.Audience) ? null : opts.Audience; + +return new ManagementClient(new ManagementClientOptions +{ +Domain = opts.Domain, +TokenProvider = new ClientCredentialsTokenProvider( +opts.Domain, +opts.ClientId, +opts.ClientSecret, +audience: audience) +}); +}); + +services.AddScoped(); +return services; +} +} +``` + +### Features/Admin/Users/UserManagementService.cs + +Key differences from the old v7 pattern: + +- Use `IManagementApiClient`, not `ManagementApiClient` +- Use `Auth0.ManagementApi.Users` request/response types +- Let the SDK manage M2M tokens internally +- Keep app-level caching for user summaries, role lists, and role-name lookups + +```csharp +using System.Buffers.Binary; +using System.Text.Json; +using Auth0.ManagementApi; +using Auth0.ManagementApi.Users; +using Domain.Abstractions; +using Domain.Features.Admin.Abstractions; +using Domain.Features.Admin.Models; +using Microsoft.Extensions.Caching.Distributed; +using Microsoft.Extensions.Caching.Memory; + +namespace YourApp.Features.Admin.Users; + +public sealed class UserManagementService : IUserManagementService +{ +private const string RolesCacheKey = "Auth0Management:Roles"; +private const string UserListCacheKeyPrefix = "auth0_users_page_"; +private const string UserByIdCacheKeyPrefix = "auth0_user_"; +private const string RolesListCacheKey = "auth0_roles_list"; +private const string UserListVersionKey = "auth0_users_version"; + +private static readonly TimeSpan UserListTtl = TimeSpan.FromMinutes(5); +private static readonly TimeSpan UserByIdTtl = TimeSpan.FromMinutes(10); +private static readonly TimeSpan RolesListTtl = TimeSpan.FromMinutes(30); + +private readonly IMemoryCache _cache; +private readonly IDistributedCache _distributedCache; +private readonly IManagementApiClient _managementClient; +private readonly ILogger _logger; + +public UserManagementService( +IMemoryCache cache, +IDistributedCache distributedCache, +IManagementApiClient managementClient, +ILogger logger) +{ +_cache = cache; +_distributedCache = distributedCache; +_managementClient = managementClient; +_logger = logger; +} + +public async Task>> ListUsersAsync( +int page, +int perPage, +CancellationToken ct) +{ +var version = await GetUserListVersionAsync(ct).ConfigureAwait(false); +var cacheKey = $"{UserListCacheKeyPrefix}{version}_{page}_{perPage}"; +var cached = await GetFromDistributedCacheAsync>(cacheKey, ct) +.ConfigureAwait(false); +if (cached is not null) return Result.Ok>(cached); + +var auth0Page = Math.Max(0, page - 1); +var pager = await _managementClient.Users +.ListAsync(new ListUsersRequestParameters { Page = auth0Page, PerPage = perPage }, null, ct) +.ConfigureAwait(false); + +var summaries = await Task.WhenAll(pager.CurrentPage.Items.Select(async user => +{ +var rolesPager = await _managementClient.Users.Roles +.ListAsync(user.UserId!, new ListUserRolesRequestParameters { PerPage = 100 }, null, ct) +.ConfigureAwait(false); + +return new AdminUserSummary +{ +UserId = user.UserId ?? string.Empty, +Email = user.Email ?? string.Empty, +Name = user.Name ?? user.Email ?? string.Empty, +Picture = user.Picture ?? string.Empty, +Roles = rolesPager.CurrentPage.Items.Select(r => r.Name ?? string.Empty).ToList(), +LastLogin = ParseLastLogin(user.LastLogin), +IsBlocked = user.Blocked ?? false +}; +})).ConfigureAwait(false); + +var result = summaries.ToList(); +await SetInDistributedCacheAsync(cacheKey, result, UserListTtl, ct).ConfigureAwait(false); +return Result.Ok>(result); +} + +public async Task> GetUserByIdAsync(string userId, CancellationToken ct) +{ +var user = await _managementClient.Users +.GetAsync(userId, new GetUserRequestParameters(), null, ct) +.ConfigureAwait(false); + +var rolesPager = await _managementClient.Users.Roles +.ListAsync(userId, new ListUserRolesRequestParameters { PerPage = 100 }, null, ct) +.ConfigureAwait(false); + +return Result.Ok(new AdminUserSummary +{ +UserId = user.UserId ?? string.Empty, +Email = user.Email ?? string.Empty, +Name = user.Name ?? user.Email ?? string.Empty, +Picture = user.Picture ?? string.Empty, +Roles = rolesPager.CurrentPage.Items.Select(r => r.Name ?? string.Empty).ToList(), +LastLogin = ParseLastLogin(user.LastLogin), +IsBlocked = user.Blocked ?? false +}); +} + +public async Task> AssignRolesAsync(string userId, IEnumerable roleNames, CancellationToken ct) +{ +var roleMap = await GetRoleMapAsync(ct).ConfigureAwait(false); +var roleIds = roleNames.Select(name => roleMap[name]).ToArray(); + +await _managementClient.Users.Roles +.AssignAsync(userId, new AssignUserRolesRequestContent { Roles = roleIds }, null, ct) +.ConfigureAwait(false); + +return Result.Ok(true); +} + +public async Task> RemoveRolesAsync(string userId, IEnumerable roleNames, CancellationToken ct) +{ +var roleMap = await GetRoleMapAsync(ct).ConfigureAwait(false); +var roleIds = roleNames.Select(name => roleMap[name]).ToArray(); + +await _managementClient.Users.Roles +.DeleteAsync(userId, new DeleteUserRolesRequestContent { Roles = roleIds }, null, ct) +.ConfigureAwait(false); + +return Result.Ok(true); +} + +public async Task>> ListRolesAsync(CancellationToken ct) +{ +var pager = await _managementClient.Roles +.ListAsync(new ListRolesRequestParameters { PerPage = 100 }, null, ct) +.ConfigureAwait(false); + +return Result.Ok>(pager.CurrentPage.Items +.Select(r => new RoleAssignment +{ +RoleId = r.Id ?? string.Empty, +RoleName = r.Name ?? string.Empty, +Description = r.Description ?? string.Empty +}) +.ToList()); +} + +private async Task GetFromDistributedCacheAsync(string key, CancellationToken ct) => +(await _distributedCache.GetAsync(key, ct).ConfigureAwait(false)) is { } bytes +? JsonSerializer.Deserialize(bytes) +: default; + +private async Task SetInDistributedCacheAsync(string key, T value, TimeSpan ttl, CancellationToken ct) => +await _distributedCache.SetAsync( +key, +JsonSerializer.SerializeToUtf8Bytes(value), +new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = ttl }, +ct).ConfigureAwait(false); + +private async Task GetUserListVersionAsync(CancellationToken ct) +{ +var bytes = await _distributedCache.GetAsync(UserListVersionKey, ct).ConfigureAwait(false); +return bytes is null ? 0L : BinaryPrimitives.ReadInt64LittleEndian(bytes); +} + +private async Task> GetRoleMapAsync(CancellationToken ct) +{ +var map = await _cache.GetOrCreateAsync(RolesCacheKey, async entry => +{ +var pager = await _managementClient.Roles +.ListAsync(new ListRolesRequestParameters { PerPage = 100 }, null, ct) +.ConfigureAwait(false); + +entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30); +return pager.CurrentPage.Items +.Where(r => r.Name is not null && r.Id is not null) +.ToDictionary(r => r.Name!, r => r.Id!, StringComparer.OrdinalIgnoreCase); +}).ConfigureAwait(false); + +return map ?? []; +} + +private static DateTimeOffset? ParseLastLogin(UserDateSchema? lastLogin) +{ +if (lastLogin is null) return null; +return lastLogin.TryGetString(out var s) && DateTimeOffset.TryParse(s, out var dto) ? dto : null; +} +} +``` + +**Note**: The real app keeps additional logging, validation, and cache-invalidation behavior around these methods. The key point is the v8 API shape and token-provider registration. + +## UI Components + +The current app composes the admin user experience from these pieces: + +- `Components/Pages/Admin/Users.razor` — page entry point, protected by `AdminPolicy` +- `Components/Admin/Users/UserListTable.razor` — tabular user display +- `Components/Admin/Users/EditUserRolesModal.razor` — add/remove role workflow +- `Components/Admin/Users/RoleBadge.razor` — role chip rendering +- `Components/Admin/Users/UserAuditLogPanel.razor` — optional audit detail display + +## Configuration + +### appsettings.json + +```json +{ + "Auth0Management": { + "ClientId": "", + "ClientSecret": "", + "Domain": "", + "Audience": "" + } +} +``` + +### User Secrets (Development) + +```bash +dotnet user-secrets set "Auth0Management:ClientId" "YOUR_M2M_CLIENT_ID" +dotnet user-secrets set "Auth0Management:ClientSecret" "YOUR_M2M_CLIENT_SECRET" +dotnet user-secrets set "Auth0Management:Domain" "your-tenant.auth0.com" +dotnet user-secrets set "Auth0Management:Audience" "https://your-tenant.auth0.com/api/v2/" +``` + +## Registration in Program.cs + +```csharp +using YourApp.Features.Admin.Users; + +builder.Services.AddUserManagement(builder.Configuration); +``` + +## Testing + +1. Log in as an admin user +2. Navigate to `/admin/users` +3. Verify the user list loads +4. Open the role editor and assign/remove roles +5. Verify the new roles appear after cache invalidation + +## Troubleshooting + +### 401 Unauthorized from the Management API + +- Confirm the M2M app is authorized for the Auth0 Management API +- Verify `Domain`, `ClientId`, `ClientSecret`, and `Audience` +- Check the `ClientCredentialsTokenProvider` configuration in `AddUserManagement()` + +### 403 Forbidden + +- Ensure the M2M app has the required scopes +- Confirm the signed-in app user has the `Admin` role before exposing admin UI + +### Empty Role List + +- Verify roles exist in the tenant +- Confirm `ListRolesAsync` is reaching the Auth0 tenant you expect diff --git a/.github/skills/implement-auth0-authentication/references/auth-implementation.md b/.github/skills/implement-auth0-authentication/references/auth-implementation.md new file mode 100644 index 0000000..dd3da67 --- /dev/null +++ b/.github/skills/implement-auth0-authentication/references/auth-implementation.md @@ -0,0 +1,516 @@ +# Core Implementation Code Patterns + +This reference provides the complete code for Auth0 infrastructure classes and components. + +Replace `YourApp` with your web project's root namespace in the snippets below. + +## Auth Infrastructure Files + +### Auth/Auth0Options.cs + +Configuration model for Auth0 web application settings. + +```csharp +namespace YourApp.Auth; + +/// +/// Configuration options for Auth0 authentication. +/// +public sealed class Auth0Options +{ + /// + /// Gets or sets the Auth0 domain (e.g., your-tenant.auth0.com). + /// + public string Domain { get; set; } = string.Empty; + + /// + /// Gets or sets the Auth0 client ID for this application. + /// + public string ClientId { get; set; } = string.Empty; + + /// + /// Gets or sets the Auth0 client secret for this application. + /// + public string ClientSecret { get; set; } = string.Empty; + + /// + /// Gets or sets the custom namespace for Auth0 role claims. + /// Example: "https://issuetracker.com/roles" + /// This must match the claim namespace configured in your Auth0 tenant (Action/Rule). + /// + public string RoleClaimNamespace { get; set; } = string.Empty; +} +``` + +### Auth/AuthorizationRoles.cs + +Role name constants. + +```csharp +namespace YourApp.Auth; + +/// +/// Defines role names used in authorization. +/// These roles should match the roles configured in Auth0. +/// +public static class AuthorizationRoles +{ + /// + /// Admin role with full access to the application. + /// + public const string Admin = "Admin"; + + /// + /// Standard user role with basic access. + /// + public const string User = "User"; +} +``` + +### Auth/AuthorizationPolicies.cs + +Authorization policy name constants. + +```csharp +namespace YourApp.Auth; + +/// +/// Defines authorization policy names for the application. +/// +public static class AuthorizationPolicies +{ + /// + /// Policy name for users with the Admin role. + /// + public const string AdminPolicy = "AdminPolicy"; + + /// + /// Policy name for users with the User role. + /// + public const string UserPolicy = "UserPolicy"; +} +``` + +### Auth/Auth0ClaimsTransformation.cs + +Claims transformation service that maps Auth0's custom role claims to ASP.NET Core's standard role claim type. + +```csharp +using System.Security.Claims; +using Microsoft.AspNetCore.Authentication; + +namespace YourApp.Auth; + +/// +/// Transforms Auth0 custom role claims to ASP.NET Core standard role claims. +/// Auth0 sends roles in a namespaced claim (e.g., "https://issuetracker.com/roles"), +/// but ASP.NET Core's RequireRole() expects claims with type ClaimTypes.Role. +/// This transformation maps Auth0 roles to the standard claim type. +/// +public sealed class Auth0ClaimsTransformation : IClaimsTransformation +{ + private readonly string _roleClaimNamespace; + private readonly ILogger _logger; + + public Auth0ClaimsTransformation( + IConfiguration configuration, + ILogger logger) + { + _logger = logger; + + // Get the Auth0 role claim namespace from configuration + var auth0Options = configuration.GetSection("Auth0").Get(); + _roleClaimNamespace = auth0Options?.RoleClaimNamespace ?? string.Empty; + + if (string.IsNullOrEmpty(_roleClaimNamespace)) + { + _logger.LogInformation( + "Auth0:RoleClaimNamespace is not configured. " + + "Will fall back to reading the standard 'roles' JWT claim for role mapping."); + } + } + + /// + /// Transforms the user's claims by mapping Auth0 custom role claims to standard role claims. + /// Pass 1: uses the configured namespace claim type. + /// Pass 2: falls back to the bare "roles" JWT claim. + /// Pass 3: auto-detects any namespaced claim type ending in "/roles" when Passes 1 and 2 + /// find nothing, guarding against misconfigured Auth0:RoleClaimNamespace. + /// + public Task TransformAsync(ClaimsPrincipal principal) + { + if (principal.Identity is not ClaimsIdentity { IsAuthenticated: true } identity) + return Task.FromResult(principal); + + var rolesAdded = 0; + + // Pass 1: use configured namespace (e.g., "https://issuetracker.com/roles") + if (!string.IsNullOrEmpty(_roleClaimNamespace)) + { + var auth0RoleClaims = principal.FindAll(_roleClaimNamespace).ToList(); + rolesAdded += MapRoleClaims(identity, auth0RoleClaims); + } + + // Pass 2: fallback — read standard "roles" JWT claim when namespace is absent + if (rolesAdded == 0) + { + var standardRoleClaims = principal.FindAll("roles").ToList(); + rolesAdded += MapRoleClaims(identity, standardRoleClaims); + } + + // Pass 3: auto-detect — scan for any namespaced role claim type when Passes 1 & 2 found nothing + if (rolesAdded == 0) + { + var autoDetectedClaims = principal.Claims + .Where(c => IsLikelyRoleClaimType(c.Type)) + .ToList(); + + if (autoDetectedClaims.Count > 0) + { + _logger.LogInformation( + "Auto-detected role claim type(s): {Types}. Consider setting Auth0:RoleClaimNamespace.", + string.Join(", ", autoDetectedClaims.Select(c => c.Type).Distinct())); + + rolesAdded += MapRoleClaims(identity, autoDetectedClaims); + } + } + + if (rolesAdded > 0) + { + _logger.LogDebug( + "Transformed {Count} role claim(s) for user '{UserId}'.", + rolesAdded, + principal.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "unknown"); + } + + return Task.FromResult(principal); + } + + /// + /// Returns true when claimType looks like a namespaced Auth0 role claim. + /// + private static bool IsLikelyRoleClaimType(string claimType) + { + // Skip standard claim types already checked in Passes 1 and 2 + if (claimType.Equals(ClaimTypes.Role, StringComparison.OrdinalIgnoreCase)) return false; + if (claimType.Equals("roles", StringComparison.OrdinalIgnoreCase)) return false; + // Match namespaced role claims like "https://*/roles" + return claimType.EndsWith("/roles", StringComparison.OrdinalIgnoreCase); + } + + /// + /// Maps role claims (from any source) to standard ASP.NET Core role claims. + /// Handles multiple role formats: JSON arrays, comma-separated strings, or single values. + /// + private int MapRoleClaims(ClaimsIdentity identity, List roleClaims) + { + var added = 0; + foreach (var roleClaim in roleClaims) + { + var roleValue = roleClaim.Value; + + if (roleValue.StartsWith('[') && roleValue.EndsWith(']')) + { + try + { + var roles = System.Text.Json.JsonSerializer.Deserialize(roleValue); + if (roles is not null) + { + foreach (var role in roles) + { + if (!identity.HasClaim(ClaimTypes.Role, role)) + { + identity.AddClaim(new Claim(ClaimTypes.Role, role)); + added++; + _logger.LogDebug("Mapped role '{Role}' to standard role claim.", role); + } + } + } + } + catch (System.Text.Json.JsonException ex) + { + _logger.LogWarning(ex, "Failed to parse role claim as JSON array: {Value}", roleValue); + } + } + else if (roleValue.Contains(',')) + { + var roles = roleValue.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); + foreach (var role in roles) + { + if (!identity.HasClaim(ClaimTypes.Role, role)) + { + identity.AddClaim(new Claim(ClaimTypes.Role, role)); + added++; + _logger.LogDebug("Mapped role '{Role}' to standard role claim.", role); + } + } + } + else + { + // Skip empty or whitespace-only role values + if (string.IsNullOrWhiteSpace(roleValue)) + continue; + + if (!identity.HasClaim(ClaimTypes.Role, roleValue)) + { + identity.AddClaim(new Claim(ClaimTypes.Role, roleValue)); + added++; + _logger.LogDebug("Mapped role '{Role}' to standard role claim.", roleValue); + } + } + } + return added; + } +} +``` + +## UI Components + +### Components/Layout/LoginDisplay.razor + +Login/logout UI with user greeting and profile link. + +```razor +@inject NavigationManager Navigation + +@{ + var currentPath = Navigation.ToBaseRelativePath(Navigation.Uri); + var returnUrl = string.IsNullOrWhiteSpace(currentPath) ? "/" : $"/{currentPath}"; +} + + + +
+ + Hey @context.User.Identity?.Name! + +
+ + + +
+ + + Log in + + +``` + +**Usage**: Place in your navigation layout (e.g., `NavMenu.razor` or `MainLayout.razor`). + +### Components/Layout/LoginComponent.razor + +Minimal login/logout buttons. + +```razor +@inject NavigationManager Navigation + +@{ + var currentPath = Navigation.ToBaseRelativePath(Navigation.Uri); + var returnUrl = string.IsNullOrWhiteSpace(currentPath) ? "/" : $"/{currentPath}"; +} + + + +
+ + + +
+ + Log in + + +``` + +**Usage**: Alternative minimal version for simple layouts. + +### Components/User/Profile.razor + +User profile page displaying claims, roles, profile picture, and debug information. + +```razor +@page "/profile" + +@using System.Security.Claims +@using Microsoft.Extensions.Configuration +@attribute [Authorize] +@inject IConfiguration Configuration + +

User Profile

+ +
+ + + +
+

Profile Information

+ +
+
+

Basic Information

+
+

+ Name: + @_username +

+

+ Email: + @_emailAddress +

+

+ User ID: + @_userId +

+
+
+ +
+

Roles & Permissions

+
+ @if (_roles.Any()) + { +

+ Roles: +

+
    + @foreach (var role in _roles) + { +
  • @role
    • + } +
+ } + else + { +

No roles assigned

+ } +
+
+ +
+ Profile Picture: + @if (!string.IsNullOrEmpty(_picture)) + { + Profile Picture + } + else + { +
+ ? +
+ } +
+
+
+ +
+

All Claims

+

Debug information showing all claims for this user:

+ +
+ + + + + + + + + @foreach (var claim in context.User.Claims.OrderBy(c => c.Type)) + { + + + + + } + +
Claim TypeValue
@claim.Type@claim.Value
+
+
+ + +
+ +@code { + [CascadingParameter] private Task? AuthenticationState { get; set; } + + private string _userId = ""; + private string _username = ""; + private string _emailAddress = ""; + private string _picture = ""; + private List _roles = new(); + + protected override async Task OnInitializedAsync() + { + if (AuthenticationState is not null) + { + var state = await AuthenticationState; + + _username = state.User.Identity?.Name ?? string.Empty; + + _userId = state.User.Claims + .Where(c => c.Type.Equals(ClaimTypes.NameIdentifier)) + .Select(c => c.Value) + .FirstOrDefault() ?? string.Empty; + + _emailAddress = state.User.Claims + .Where(c => c.Type.Equals(ClaimTypes.Email)) + .Select(c => c.Value) + .FirstOrDefault() ?? string.Empty; + + _picture = state.User.Claims + .Where(c => c.Type.Equals("picture")) + .Select(c => c.Value) + .FirstOrDefault() ?? string.Empty; + + var roleNamespace = Configuration["Auth0:RoleClaimNamespace"] ?? string.Empty; + _roles = GetAllRoleClaims(state.User, roleNamespace); + } + + await base.OnInitializedAsync(); + } + + // Helper to get all role claims for a user + private static List GetAllRoleClaims(ClaimsPrincipal user, string? roleClaimNamespace = null) + { + var roleTypesList = new List { ClaimTypes.Role, "role", "roles" }; + + if (!string.IsNullOrWhiteSpace(roleClaimNamespace)) + roleTypesList.Add(roleClaimNamespace); + + return user.Claims + .Where(c => roleTypesList.Contains(c.Type, StringComparer.OrdinalIgnoreCase)) + .Select(c => c.Value) + .Where(v => !string.IsNullOrWhiteSpace(v)) + .Distinct() + .ToList(); + } +} +``` + +**Note**: Update CSS classes to match your application's styling framework (Tailwind, Bootstrap, etc.). + +## Auth0 Action Example + +To include roles in the ID token, create an Auth0 Action (Actions → Flows → Login): + +```javascript +/** +* Handler that will be called during the execution of a PostLogin flow. +* +* @param {Event} event - Details about the user and the context in which they are logging in. +* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login. +*/ +exports.onExecutePostLogin = async (event, api) => { + const namespace = 'https://yourapp.com'; + if (event.authorization) { + api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles); + api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles); + } +}; +``` + +Replace `https://yourapp.com` with your actual namespace that matches the `Auth0:RoleClaimNamespace` configuration. diff --git a/.github/skills/implement-auth0-authentication/references/configuration-prompts.md b/.github/skills/implement-auth0-authentication/references/configuration-prompts.md new file mode 100644 index 0000000..8a5cc2a --- /dev/null +++ b/.github/skills/implement-auth0-authentication/references/configuration-prompts.md @@ -0,0 +1,232 @@ +# Configuration Prompts + +When gathering Auth0 configuration, prompt the user with clear questions and examples. **Do not proceed until all required values are collected.** + +## Auth0 Web Application (OIDC) — Required + +### Auth0 Domain +**Prompt**: "What is your Auth0 tenant domain? (e.g., `your-tenant.auth0.com` or `your-tenant.us.auth0.com`)" + +**Where to find**: Auth0 Dashboard → Applications → [Your Application] → Settings → Domain + +**Example**: `dev-abc123.us.auth0.com` + +### Client ID +**Prompt**: "What is the Client ID for your Auth0 web application?" + +**Where to find**: Auth0 Dashboard → Applications → [Your Application] → Settings → Client ID + +**Example**: `abc123XYZ456def789` + +**Note**: This is the OIDC web application Client ID, not the Management API M2M Client ID. + +### Client Secret +**Prompt**: "What is the Client Secret for your Auth0 web application? (This will be stored in user secrets.)" + +**Where to find**: Auth0 Dashboard → Applications → [Your Application] → Settings → Client Secret + +**Example**: `AbC123-XyZ456_DeF789_GhI012` + +**Security Note**: This value will be stored in user secrets for development and should be stored in a secure vault (Azure Key Vault, AWS Secrets Manager) for production. Never commit to source control. + +### Role Claim Namespace +**Prompt**: "What is the custom namespace for Auth0 role claims? (e.g., `https://yourapp.com/roles`)" + +**Where to find**: This is configured in your Auth0 Action or Rule. It's the custom claim namespace you use when adding roles to the ID token. + +**Example**: `https://issuetracker.com/roles` + +**Default behavior**: If this is not configured or left empty, the skill will use a fallback detection strategy that checks standard `roles` claims and auto-detects namespaced role claims ending in `/roles`. + +**Auth0 Action Example**: +```javascript +exports.onExecutePostLogin = async (event, api) => { + const namespace = 'https://yourapp.com'; + if (event.authorization) { + api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles); + } +}; +``` + +## Callback and Logout URLs — Required + +### Callback URL +**Prompt**: "What is the callback URL for your application? (Development example: `https://localhost:5001/callback`, Production: `https://yourdomain.com/callback`)" + +**Where to configure**: Auth0 Dashboard → Applications → [Your Application] → Settings → Allowed Callback URLs + +**Development Example**: `https://localhost:5001/callback` + +**Production Example**: `https://yourdomain.com/callback` + +**Note**: The callback URL must match exactly (protocol, domain, port, path). The Auth0 SDK automatically handles the `/callback` endpoint. + +### Logout URL +**Prompt**: "What is the logout redirect URL for your application? (Development example: `https://localhost:5001/`, Production: `https://yourdomain.com/`)" + +**Where to configure**: Auth0 Dashboard → Applications → [Your Application] → Settings → Allowed Logout URLs + +**Development Example**: `https://localhost:5001/` + +**Production Example**: `https://yourdomain.com/` + +## Auth0 Management API (M2M) — Optional (Required for Admin User Management) + +Ask the user: "Do you want to include admin user management features? This requires an Auth0 Management API Machine-to-Machine (M2M) application. (yes/no)" + +If yes, prompt for: + +### Management API Client ID +**Prompt**: "What is the Client ID for your Auth0 Management API M2M application?" + +**Where to find**: Auth0 Dashboard → Applications → [M2M Application] → Settings → Client ID + +**Example**: `xyz789ABC123ghi456` + +**Note**: This is different from the OIDC web app Client ID. + +### Management API Client Secret +**Prompt**: "What is the Client Secret for your Auth0 Management API M2M application? (This will be stored in user secrets.)" + +**Where to find**: Auth0 Dashboard → Applications → [M2M Application] → Settings → Client Secret + +**Example**: `Xyz789-Abc123_Ghi456_Jkl789` + +**Security Note**: Store in user secrets (development) or secure vault (production). + +### Management API Domain +**Prompt**: "What is the Auth0 domain for the Management API? (Usually the same as your Auth0:Domain, e.g., `your-tenant.auth0.com`)" + +**Where to find**: Same as Auth0 Domain, unless using a custom domain. + +**Example**: `dev-abc123.us.auth0.com` + +### Management API Audience +**Prompt**: "What is the Auth0 Management API audience? (Format: `https://your-tenant.auth0.com/api/v2/`)" + +**Where to find**: Auth0 Dashboard → Applications → APIs → Auth0 Management API → Identifier + +**Example**: `https://dev-abc123.us.auth0.com/api/v2/` + +**Note**: The trailing slash is required. + +### Management API Scopes +**Important**: Ensure the M2M application is authorized for the Auth0 Management API with the following scopes: + +- `read:users` — List and read user details +- `update:users` — Update user metadata and assign/remove roles +- `read:roles` — List available roles +- `read:users_app_metadata` — Read user app metadata +- `update:users_app_metadata` — Update user app metadata + +**Where to configure**: Auth0 Dashboard → Applications → [M2M Application] → APIs → Auth0 Management API → Authorize → Select scopes + +## Feature Selection — Optional + +### User Profile Page +**Prompt**: "Do you want to create a user profile page that displays claims and roles? (yes/no)" + +**Default**: yes + +**What it creates**: `Components/User/Profile.razor` — A Blazor page that displays the authenticated user's claims, roles, email, profile picture, and debug information. + +### Admin User Management +**Prompt**: "Do you want to include admin user management pages? This requires an Auth0 Management API M2M application. (yes/no)" + +**Default**: no (due to additional Auth0 setup required) + +**What it creates**: +- `Features/Admin/Users/UserManagementService.cs` +- `Features/Admin/Users/UserManagementExtensions.cs` +- `Features/Admin/Users/Auth0ManagementOptions.cs` +- `Components/Pages/Admin/Users.razor` +- `Components/Admin/Users/EditUserRolesModal.razor` +- `Components/Admin/Users/UserListTable.razor` +- `Components/Admin/Users/RoleBadge.razor` +- Domain contracts: `IUserManagementService`, `AdminUserSummary`, `RoleAssignment` + +## Validation + +After gathering all values: + +1. **Validate URLs**: + - Callback URL must be a valid URI with protocol, domain, and `/callback` path + - Logout URL must be a valid URI with protocol and domain + - Management API Audience must match `https://{domain}/api/v2/` + +2. **Validate Domain**: + - Domain should match pattern `*.auth0.com` or `*.us.auth0.com` or custom domain + - No protocol (`https://`) prefix + +3. **Validate Client IDs and Secrets**: + - Client ID and Client Secret should not be empty + - If Management API is requested, M2M Client ID and Secret should not be empty + +4. **Confirm with user**: + - Display all collected values (mask secrets) + - Ask "Are these values correct? (yes/no)" + - If no, re-prompt for corrections + +## Example Prompt Flow + +``` +I'll help you add Auth0 authentication to your Blazor application. I need to gather some configuration values first. + +Auth0 Web Application (OIDC): +1. What is your Auth0 tenant domain? (e.g., your-tenant.auth0.com) + > dev-abc123.us.auth0.com + +2. What is the Client ID for your Auth0 web application? + > abc123XYZ456def789 + +3. What is the Client Secret? (This will be stored securely in user secrets.) + > AbC123-XyZ456_DeF789_GhI012 + +4. What is the custom namespace for Auth0 role claims? (e.g., https://yourapp.com/roles) + > https://issuetracker.com/roles + +Callback and Logout URLs: +5. What is the callback URL for development? (e.g., https://localhost:5001/callback) + > https://localhost:5001/callback + +6. What is the logout redirect URL? (e.g., https://localhost:5001/) + > https://localhost:5001/ + +Feature Selection: +7. Do you want to create a user profile page? (yes/no) + > yes + +8. Do you want to include admin user management features? This requires an Auth0 Management API M2M application. (yes/no) + > yes + +Auth0 Management API (M2M): +9. What is the Client ID for your Auth0 Management API M2M application? + > xyz789ABC123ghi456 + +10. What is the Client Secret for your M2M application? (This will be stored securely.) + > Xyz789-Abc123_Ghi456_Jkl789 + +11. What is the Management API domain? (Usually the same as your Auth0 domain) + > dev-abc123.us.auth0.com + +12. What is the Management API audience? (Format: https://your-tenant.auth0.com/api/v2/) + > https://dev-abc123.us.auth0.com/api/v2/ + +Summary: +- Auth0 Domain: dev-abc123.us.auth0.com +- Client ID: abc123XYZ456def789 +- Client Secret: AbC***I012 (will be stored in user secrets) +- Role Claim Namespace: https://issuetracker.com/roles +- Callback URL: https://localhost:5001/callback +- Logout URL: https://localhost:5001/ +- Profile Page: Yes +- Admin User Management: Yes +- M2M Client ID: xyz789ABC123ghi456 +- M2M Client Secret: Xyz***789 (will be stored in user secrets) +- M2M Audience: https://dev-abc123.us.auth0.com/api/v2/ + +Are these values correct? (yes/no) +> yes + +Great! I'll now add Auth0 authentication to your Blazor application... +``` diff --git a/.github/skills/implement-auth0-authentication/references/program-configuration.md b/.github/skills/implement-auth0-authentication/references/program-configuration.md new file mode 100644 index 0000000..25a96db --- /dev/null +++ b/.github/skills/implement-auth0-authentication/references/program-configuration.md @@ -0,0 +1,263 @@ +# Program.cs Configuration + +Complete `Program.cs` configuration for Auth0 authentication with the same secure patterns used in the current app. + +Replace `YourApp` with your web project's root namespace in the web-layer namespaces below. + +## Required Using Statements + +```csharp +using Auth0.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authentication.Cookies; +using YourApp.Auth; +using YourApp.Features.Admin.Users; +``` + +## Authentication and Authorization Setup + +Add this configuration after the other service registrations and before the Razor component setup: + +```csharp +// Register Auth0 Management API user-management service when admin features are enabled. +builder.Services.AddUserManagement(builder.Configuration); + +// Configure authentication — Cookie-only in Testing mode; Auth0 OIDC in all other environments +if (builder.Environment.IsEnvironment("Testing")) +{ +builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) +.AddCookie(opts => opts.LoginPath = "/test/login"); +} +else +{ +var auth0Options = builder.Configuration.GetSection("Auth0").Get() +?? throw new InvalidOperationException("Auth0 configuration is missing."); + +builder.Services +.AddAuth0WebAppAuthentication(options => +{ +options.Domain = auth0Options.Domain; +options.ClientId = auth0Options.ClientId; +options.ClientSecret = auth0Options.ClientSecret; +options.Scope = "openid profile email"; +}); + +builder.Services.AddScoped(); +} + +builder.Services.AddAuthorization(options => +{ +options.AddPolicy(AuthorizationPolicies.AdminPolicy, policy => +policy.RequireRole(AuthorizationRoles.Admin)); + +options.AddPolicy(AuthorizationPolicies.UserPolicy, policy => +policy.RequireRole(AuthorizationRoles.User)); +}); +``` + +## Cascading Authentication State + +```csharp +builder.Services.AddRazorComponents() +.AddInteractiveServerComponents(); + +builder.Services.AddCascadingAuthenticationState(); +``` + +## Secure Login/Logout Endpoints + +The Auth0 SDK handles `/callback`, but the current app maps explicit login/logout endpoints so it can validate `returnUrl`, support the testing environment, and use POST + antiforgery for logout. + +```csharp +app.MapGet("/account/login", async (HttpContext context, IWebHostEnvironment env, string returnUrl = "/") => +{ +var validReturnUrl = !string.IsNullOrEmpty(returnUrl) && IsLocalUrl(returnUrl) +? returnUrl +: "/"; + +if (env.IsEnvironment("Testing")) +{ +return Results.Redirect($"/test/login?role=user&returnUrl={Uri.EscapeDataString(validReturnUrl)}"); +} + +var authenticationProperties = new AuthenticationProperties { RedirectUri = validReturnUrl }; +await context.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties); +return Results.Empty; +}).AllowAnonymous(); + +app.MapPost("/account/logout", async (HttpContext context, IWebHostEnvironment env) => +{ +var authenticationProperties = new AuthenticationProperties { RedirectUri = "/" }; + +if (!env.IsEnvironment("Testing")) +{ +await context.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties); +} + +await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme); +}).RequireAuthorization(); +``` + +### Testing-Only Login Endpoint + +```csharp +if (app.Environment.IsEnvironment("Testing")) +{ +app.MapGet("/test/login", async (HttpContext ctx, string role = "user", string returnUrl = "/") => +{ +var isAdmin = role.Equals("admin", StringComparison.OrdinalIgnoreCase); + +var claims = new List +{ +new(ClaimTypes.NameIdentifier, isAdmin ? "auth0|test-admin" : "auth0|test-user"), +new(ClaimTypes.Name, isAdmin ? "Test Admin" : "Test User"), +new(ClaimTypes.Email, isAdmin ? "admin@test.com" : "user@test.com"), +new(ClaimTypes.Role, isAdmin ? "Admin" : "User"), +}; + +var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme); +await ctx.SignInAsync(new ClaimsPrincipal(identity)); + +var safeReturn = !string.IsNullOrEmpty(returnUrl) && IsLocalUrl(returnUrl) ? returnUrl : "/"; +return Results.Redirect(safeReturn); +}).AllowAnonymous(); +} +``` + +### Local URL Validation Helper + +```csharp +static bool IsLocalUrl(string url) +{ +if (string.IsNullOrEmpty(url)) +{ +return false; +} + +if (url.StartsWith("//", StringComparison.Ordinal) || +url.StartsWith("http://", StringComparison.OrdinalIgnoreCase) || +url.StartsWith("https://", StringComparison.OrdinalIgnoreCase)) +{ +return false; +} + +return url.StartsWith("/", StringComparison.Ordinal) && !url.StartsWith("//", StringComparison.Ordinal); +} +``` + +## Middleware Pipeline + +Use explicit middleware registration rather than assuming the SDK inserted it for you: + +```csharp +var app = builder.Build(); + +// ... exception handling, HTTPS, status-code pages ... + +app.UseHttpsRedirection(); +app.UseAuthentication(); +app.UseAuthorization(); +app.UseAntiforgery(); + +app.MapStaticAssets(); +app.MapRazorComponents() +.AddInteractiveServerRenderMode(); +``` + +## Complete Example + +```csharp +using System.Security.Claims; +using Auth0.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authentication; +using Microsoft.AspNetCore.Authentication.Cookies; +using YourApp.Auth; +using YourApp.Components; +using YourApp.Features.Admin.Users; + +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddUserManagement(builder.Configuration); + +if (builder.Environment.IsEnvironment("Testing")) +{ +builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) +.AddCookie(opts => opts.LoginPath = "/test/login"); +} +else +{ +var auth0Options = builder.Configuration.GetSection("Auth0").Get() +?? throw new InvalidOperationException("Auth0 configuration is missing."); + +builder.Services +.AddAuth0WebAppAuthentication(options => +{ +options.Domain = auth0Options.Domain; +options.ClientId = auth0Options.ClientId; +options.ClientSecret = auth0Options.ClientSecret; +options.Scope = "openid profile email"; +}); + +builder.Services.AddScoped(); +} + +builder.Services.AddAuthorization(options => +{ +options.AddPolicy(AuthorizationPolicies.AdminPolicy, policy => +policy.RequireRole(AuthorizationRoles.Admin)); +options.AddPolicy(AuthorizationPolicies.UserPolicy, policy => +policy.RequireRole(AuthorizationRoles.User)); +}); + +builder.Services.AddRazorComponents() +.AddInteractiveServerComponents(); +builder.Services.AddCascadingAuthenticationState(); + +var app = builder.Build(); + +app.UseHttpsRedirection(); +app.UseAuthentication(); +app.UseAuthorization(); +app.UseAntiforgery(); + +app.MapRazorComponents() +.AddInteractiveServerRenderMode(); + +app.Run(); +``` + +## Environment Notes + +### Testing + +- Uses cookie-based auth only +- Avoids external Auth0 dependencies +- Supports `/test/login?role=user|admin` + +### Development + +- Usually reads Auth0 secrets from user secrets +- Callback URL is typically `https://localhost:5001/callback` + +### Production + +- Use Azure Key Vault, environment variables, or another secure secret store +- Ensure callback/logout URLs match the production hostname exactly + +## Troubleshooting + +### "Auth0 configuration is missing" + +- Ensure the `Auth0` section exists +- Verify user secrets or environment variables are loaded + +### Login Always Redirects Home + +- The login endpoint only accepts local `returnUrl` values +- Build links with a base-relative path such as `/issues/123`, not `https://example.com/issues/123` + +### Middleware Errors or 401s + +- Ensure `UseAuthentication()` runs before `UseAuthorization()` +- Keep both before endpoint mapping +- Leave `UseAntiforgery()` enabled so logout POSTs stay protected diff --git a/.github/workflows/squad-heartbeat.yml b/.github/workflows/squad-heartbeat.yml index a5d4be4..d91d8aa 100644 --- a/.github/workflows/squad-heartbeat.yml +++ b/.github/workflows/squad-heartbeat.yml @@ -8,8 +8,8 @@ name: Squad Heartbeat (Ralph) on: schedule: - # Every 30 minutes — adjust via cron expression as needed - - cron: '*/30 * * * *' + # Every 15 minutes — adjust via cron expression as needed + - cron: '*/15 * * * *' # React to completed work or new squad work issues: diff --git a/.github/workflows/squad-pr-auto-label.yml b/.github/workflows/squad-pr-auto-label.yml new file mode 100644 index 0000000..c0ff06f --- /dev/null +++ b/.github/workflows/squad-pr-auto-label.yml @@ -0,0 +1,94 @@ +--- +name: Squad PR Auto-Label + +on: + pull_request_target: + types: [opened, reopened, synchronize] + +permissions: + pull-requests: write + contents: read + +jobs: + auto-label: + runs-on: ubuntu-latest + steps: + - name: Auto-label PR for squad system + uses: actions/github-script@v9 + with: + script: | + const pr = context.payload.pull_request; + const author = pr.user.login; + + // Fetch current labels on the PR + const { data: currentLabels } = await github.rest.issues.listLabelsOnIssue({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number + }); + + const labelNames = currentLabels.map(l => l.name); + + // Check if already has squad labels + const hasSquadLabel = labelNames.some(name => + name === 'squad' || name.startsWith('squad:') + ); + + if (hasSquadLabel) { + core.info(`PR #${pr.number} already has squad label(s) — skipping`); + return; + } + + let labelsToAdd = []; + let commentBody = ''; + + // Handle known automation bots + const knownBots = ['dependabot[bot]', 'renovate[bot]', 'github-actions[bot]']; + if (knownBots.includes(author)) { + labelsToAdd = ['squad:boromir', 'squad']; + commentBody = [ + `### 🤖 Dependency Update PR`, + '', + `This PR was opened by **${author}** and has been automatically labeled for **Boromir** (DevOps) to review.`, + '', + `**Labels applied:**`, + `- \`squad:boromir\` — Assigned to DevOps for dependency updates`, + `- \`squad\` — In triage queue`, + '', + `> Dependency and infrastructure updates are owned by the DevOps team.` + ].join('\n'); + } else { + // Handle general PRs without squad labels + labelsToAdd = ['squad']; + commentBody = [ + `### 🏗️ PR Added to Squad Triage Queue`, + '', + `This PR has been labeled with \`squad\` and added to the triage queue.`, + '', + `**Next steps:**`, + `- The squad Lead will review and assign to an appropriate team member`, + `- A \`squad:member\` label will be added after triage`, + '', + `> If you know which squad member should handle this, you can add the appropriate \`squad:member\` label yourself.` + ].join('\n'); + } + + // Add labels + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + labels: labelsToAdd + }); + + core.info(`Added labels to PR #${pr.number}: ${labelsToAdd.join(', ')}`); + + // Post comment + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + body: commentBody + }); + + core.info(`Posted auto-label comment on PR #${pr.number}`); diff --git a/.github/workflows/squad-promote.yml b/.github/workflows/squad-promote.yml index 7d4ce51..9517262 100644 --- a/.github/workflows/squad-promote.yml +++ b/.github/workflows/squad-promote.yml @@ -86,7 +86,7 @@ jobs: EOF # Check if a promote PR already exists - EXISTING=$(gh pr list --base main --head dev --state open --json number --jq '.[0].number' || true) + EXISTING=$(gh pr list --base main --head dev --state open --json number --jq '.[0].number // empty' || true) if [ -n "$EXISTING" ]; then echo "ℹ️ Promote PR #$EXISTING already exists — updating description" gh pr edit "$EXISTING" \ diff --git a/.gitignore b/.gitignore index 19b8a53..8adcfd8 100644 --- a/.gitignore +++ b/.gitignore @@ -387,6 +387,7 @@ MigrationBackup/ # IDE / local .vscode/ +*.csproj.lscache # Test output coverage/ diff --git a/.squad/.first-run b/.squad/.first-run deleted file mode 100644 index 21f0267..0000000 --- a/.squad/.first-run +++ /dev/null @@ -1 +0,0 @@ -2026-03-26T22:54:46.392Z diff --git a/.squad/agents/aragorn/history.md b/.squad/agents/aragorn/history.md index 4b1284c..130107c 100644 --- a/.squad/agents/aragorn/history.md +++ b/.squad/agents/aragorn/history.md @@ -454,3 +454,34 @@ Full structured investigation (20 ideas, prioritised) written to: **Output:** Detailed technical analysis, risk matrix, implementation roadmap filed to `.squad/orchestration-log/2026-04-12T20-17-00Z-aragorn-full-review.md` and `.squad/decisions.md`. **Status:** ✅ Complete — Recommendation merged to team decisions. + +--- + +### 2026-05-01 — PR #265 Second Lead Review & Rejection (Re-Assessment) + +**Context:** Frodo reported completion of PR #265 Auth0 skill revision (fixing typo `implemet-...` → `implement-...`, Auth0 scope guidance, namespace clarification). Aragorn conducted second lead-review pass to validate fixes. + +**Aragorn's Role:** Lead reviewer, PR quality gate authority. + +**Findings:** +All three blockers from first review **REMAIN UNRESOLVED** on current PR revision: +1. Skill name typo (`implemet-auth0-authentication`) still present — Frodo's rename not pushed +2. Auth0 scope guidance still conflates `update:roles` with role assignment (`update:users` required) +3. Namespace examples still use `Web.*` without customization guidance for project reuse + +**Root Cause:** Frodo's reported fixes exist in local commits but were not pushed to PR remote. Indicates incomplete handoff or branch tracking failure. + +**Decision:** +- **Rejection Status:** PR #265 blocked for revision cycle 2 +- **Agent Lockout:** Gandalf and Frodo locked out this cycle (prevent overlapping fixes) +- **Handoff:** Sam assigned to next iteration with full ownership +- **Blocker Summary:** Typo, scope docs, namespace docs — 3 blockers, all unresolved + +**Actions Taken:** +- Created orchestration log: `.squad/orchestration-log/2026-05-01T04:43:52Z-aragorn-pr265-rereview.md` +- Created session log: `.squad/log/2026-05-01T04:43:52Z-pr265-second-rejection-sam-handoff.md` +- Notified Sam for next PR revision + +**Output:** Re-review rejection rationale, blocker list, Sam handoff notes. + +**Status:** ✅ Complete — Rejection logged, board notified, Sam awaiting assignment confirmation. diff --git a/.squad/agents/sam/history.md b/.squad/agents/sam/history.md index 103a8d2..1822220 100644 --- a/.squad/agents/sam/history.md +++ b/.squad/agents/sam/history.md @@ -68,3 +68,36 @@ - Team transferred from IssueManager squad (2026-03-12) - Same tech stack: .NET 10, Blazor, Aspire, MongoDB, Redis, Auth0, MediatR - Ready for scaling backend services and feature expansion + +--- + +### 2026-05-01 — PR #265 Revision Cycle 2 — Branch Investigation & Fix Coordination (Assigned) + +**Context:** PR #265 Auth0 skill second revision by Frodo failed lead review (Aragorn re-assessment). All three reported fixes missing from PR remote. Sam assigned to investigate, apply fixes, and push clean revision. + +**Sam's Role:** Interim fix coordinator (pending role confirmation). + +**Blockers to Resolve:** +1. **Typo:** Rename `.github/skills/implemet-auth0-authentication/` → `implement-auth0-authentication` +2. **Auth0 Scope Docs:** Clarify `update:users` required for role assignment (not `update:roles`) +3. **Namespace Guidance:** Standardize examples with `YourApp.*` placeholder and customization instruction + +**Assigned Responsibilities:** +1. Investigate Frodo's branch state — confirm local commits, verify push status +2. Validate all blockers on current PR revision +3. Complete or re-apply all three fixes cohesively +4. Local testing: build, tests, pre-push gate validation +5. Push clean revision to PR #265 remote +6. Notify Aragorn when ready for third-pass lead-review + +**Coordination:** +- Gandalf, Frodo locked out this cycle +- Aragorn scheduled for post-push lead-review +- Board: PR #265 → Sam ownership, Aragorn review queue + +**Output Expected:** +- Clean PR revision with all 3 blockers resolved +- Build + tests passing +- Ready for Aragorn lead-review merge gate + +**Status:** ⏳ Assigned — awaiting investigation start. diff --git a/.squad/ceremonies.md b/.squad/ceremonies.md index b6ae801..7889f5b 100644 --- a/.squad/ceremonies.md +++ b/.squad/ceremonies.md @@ -204,7 +204,7 @@ Fix agent: please push corrections to `{branch}` and comment when ready for re-r ### Merge Conflict Resolution Ceremony - **Trigger:** Ralph detects `mergeable: CONFLICTED` on an open PR -- **When:** as soon as conflict is detected (typically after `main` advances) +- **When:** as soon as conflict is detected (typically after `dev` advances) - **Facilitator:** Aragorn (decides resolver and strategy) - **Purpose:** Unblock PRs with merge conflicts without violating review integrity @@ -307,7 +307,7 @@ Print surviving branches for visibility: ```bash echo "--- Remaining local branches ---" -git branch -vv | grep -v "^\* main" +git branch -vv | grep -v "^\* dev" echo "--- Remaining remote squad/ branches ---" git branch -r | grep 'origin/squad/' || echo "(none)" @@ -316,9 +316,9 @@ git branch -r | grep 'origin/squad/' || echo "(none)" #### Full one-liner (for convenience) ```bash -git checkout main && git pull origin main && git fetch --prune && \ -git branch -r --merged origin/main | grep 'origin/squad/' | sed 's|origin/||' | xargs -r -I{} git push origin --delete {} && \ -git branch --merged main | grep -E '^\s+squad/' | xargs -r git branch -d && \ +git checkout dev && git pull origin dev && git fetch --prune && \ +git branch -r --merged origin/dev | grep 'origin/squad/' | sed 's|origin/||' | xargs -r -I{} git push origin --delete {} && \ +git branch --merged dev | grep -E '^\s+squad/' | xargs -r git branch -d && \ git branch -vv | grep ': gone]' | grep 'squad/' | awk '{print $1}' | xargs -r git branch -D && \ echo "✅ Orphan branch cleanup complete." ``` diff --git a/.squad/config.json b/.squad/config.json deleted file mode 100644 index 8174511..0000000 --- a/.squad/config.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "version": 1 -} \ No newline at end of file diff --git a/.squad/decisions.md b/.squad/decisions.md index afa7c2d..8ecb38c 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -2081,3 +2081,48 @@ Phase 2 — Documentation & Polish (P1, ~1.5 hours): **Approval Required:** Matthew Paulosky (repository owner) **Source:** .squad/decisions/inbox/aragorn-dev-main-branching.md (merged 2026-04-12) + +--- + +## PR #265 Revision Cycle 2: Blocker Verification & Agent Lockout Decision + +**Date:** 2026-05-01 +**Context:** Frodo reported completion of three-part Auth0 skill revision (typo rename, scope docs, namespace guidance). Aragorn lead-review found all blockers **unresolved** on PR remote. + +### Issue + +- **Expected State:** PR #265 with all three blockers fixed, build & tests passing +- **Actual State:** All three blockers still present; Frodo's reported local commits not pushed +- **Impact:** Revision cycle fails; PR blocked indefinitely + +### Root Cause + +Frodo's fixes exist in local commits but were **not pushed** to PR remote. Indicates either: +1. Local branch tracking failure +2. Incomplete handoff / push process +3. Branch reset after commits + +### Decision + +**Reject PR #265 Revision Cycle 2.** Agent reassignment to Sam with explicit blockers list. + +**Agent Lockout Rationale:** Gandalf and Frodo locked out this cycle to prevent overlapping fix attempts. Sam owns next iteration with full authority to investigate branch state, re-apply fixes if needed, and push clean revision. + +**Blocker Specification for Sam:** +1. Typo: Rename folder/metadata `implemet-...` → `implement-...` +2. Auth0 Scopes: Document `update:users` required for role assignment (not `update:roles`) +3. Namespace: Standardize `YourApp.*` placeholder with customization guidance + +### Team Impact + +- **Coordination:** Three-agent sequence (Frodo failed → Sam owns) reduces risk of duplicate fixes +- **Quality Gate:** Aragorn lead-review remains mandatory pre-merge +- **Timeline:** One additional revision cycle expected before merge + +### Recorded In + +- Orchestration Log: `.squad/orchestration-log/2026-05-01T04:43:52Z-aragorn-pr265-rereview.md` +- Session Log: `.squad/log/2026-05-01T04:43:52Z-pr265-second-rejection-sam-handoff.md` +- Agent Histories: Aragorn & Sam (2026-05-01 entries) + +**Status:** ✅ Decision logged, agents notified, board queued for Sam assignment. diff --git a/.squad/log/2025-03-21T15-05-mongodb-config-fix.md b/.squad/log/2025-03-21T15-05-mongodb-config-fix.md deleted file mode 100644 index 79b49fc..0000000 --- a/.squad/log/2025-03-21T15-05-mongodb-config-fix.md +++ /dev/null @@ -1,12 +0,0 @@ -# Session Log: MongoDB Config Fix - -**Timestamp:** 2025-03-21T15:05:00Z -**Agent:** Sam (Backend Developer) -**Topic:** MongoDB connection string configuration fallback - -## Summary - -Fixed `TimeoutException` in Web project startup by implementing config fallback logic. EF Core MongoDB provider (`MongoDB:ConnectionString`) now checks `ConnectionStrings:mongodb` (Aspire-injected) when default is empty or localhost. Updated `ServiceCollectionExtensions.cs` to read config section before Options binding, and cleared hardcoded localhost from `appsettings.Development.json`. - -**Files Changed:** 2 -**Status:** ✅ Complete diff --git a/.squad/log/2025-03-29T08-33-36Z-ralph-session-complete.md b/.squad/log/2025-03-29T08-33-36Z-ralph-session-complete.md deleted file mode 100644 index dce0b36..0000000 --- a/.squad/log/2025-03-29T08-33-36Z-ralph-session-complete.md +++ /dev/null @@ -1,41 +0,0 @@ -# Ralph Session Complete — Session Log - -**Timestamp:** 2025-03-29T08:33:36Z -**Session Topic:** PR #86 E2E test failures, Issues page bugs, accessibility -**Outcome:** MERGED ✅ - -## Session Summary - -### Problem Identified -Ralph discovered 2 failing Aspire+Playwright E2E tests within PR #86, plus related Issues page bugs and accessibility issues. - -### Team Work -1. **Ralph** (QA Lead) - - Identified failing E2E tests - - Diagnosed polling issues (/health → /alive endpoint) - - Flagged theme localStorage assertion failures - - Reported dual theme system conflict - -2. **Pippin** (Frontend Engineer) - - Fixed E2E test startup polling logic - - Updated theme localStorage key assertions - - Unified theme system handling - -3. **Aragorn** (Lead Developer) - - Resolved theme system conflict - - Removed redundant theme-manager.js - - Unified themeManager + tailwind-color-theme approach - -### Results -- ✅ All 23 CI checks passed -- ✅ All 40 E2E tests passed -- ✅ PR merged to main (squash commit) -- ✅ Branch deleted - -### Artifacts -- Orchestration log: `2025-03-29T08-33-36Z-pr86-merged.md` -- Test results: All 40 E2E tests passing -- CI pipeline: 23/23 checks green - -### Notes -Board is clear — no blocking issues remain. Ready for deployment. diff --git a/.squad/log/2026-03-17T17-26-00Z-di-lifetime-fix.md b/.squad/log/2026-03-17T17-26-00Z-di-lifetime-fix.md deleted file mode 100644 index 7c21c10..0000000 --- a/.squad/log/2026-03-17T17-26-00Z-di-lifetime-fix.md +++ /dev/null @@ -1,19 +0,0 @@ -# Session Log: DI Lifetime Fix - -**Timestamp:** 2026-03-17T17:26:00Z -**Topic:** Dependency Injection lifetime validation fixes - -## Work Completed - -Sam fixed two startup-blocking DI mismatches: - -1. **ServiceCollectionExtensions.cs** → Scoped `DbContextFactory` registration -2. **BulkOperationBackgroundService.cs** → Removed unused scoped dependency - -## Outcome - -✅ Build passes, startup validation resolved - -## Decision Recorded - -`.squad/decisions/inbox/sam-di-lifetime-fix.md` — establishes team rules for DbContext/DbContextFactory alignment and singleton background service patterns diff --git a/.squad/log/2026-03-17T18-54-25Z-auth0-nav-fix.md b/.squad/log/2026-03-17T18-54-25Z-auth0-nav-fix.md deleted file mode 100644 index e92f678..0000000 --- a/.squad/log/2026-03-17T18-54-25Z-auth0-nav-fix.md +++ /dev/null @@ -1,57 +0,0 @@ -# Session: Auth0 Navigation & Role Fix (2026-03-17T18:54:25Z) - -**Duration:** 2 agents, parallel execution -**Agents:** Gandalf (Security), Legolas (Frontend) -**Outcome:** Both missions completed successfully - ---- - -## Summary - -Team executed coordinated sprint to fix Auth0 role-based authorization and implement role-gated navigation UI. - -**Gandalf** implemented claims transformation to map Auth0 custom role claims to ASP.NET Core standard claims, unblocking role-based authorization. - -**Legolas** built navigation sidebar component with role-based visibility and redesigned landing page for authenticated/unauthenticated states. - -**Result:** Authentication and navigation infrastructure now functional. Both builds pass. - ---- - -## Key Decisions Recorded - -1. **Auth0 Role Claim Mapping** (IClaimsTransformation service) -2. **Navigation Menu Architecture** (sidebar + dual-state landing) -3. **Switch to MongoDB Atlas** (previously recorded; included in merged decisions) -4. **User Directive:** MongoDB connection string from Atlas (not container) - ---- - -## Next Steps - -- Configure Auth0 tenant role claim namespace in user secrets (both developers) -- Test role-based page access with Admin and User roles -- Consider mobile responsiveness for sidebar (future sprint) -- Expand navigation items as new features are added - ---- - -## Files - -**Orchestration Logs:** -- `.squad/orchestration-log/2026-03-17T18-54-25Z-gandalf.md` -- `.squad/orchestration-log/2026-03-17T18-54-25Z-legolas.md` - -**Decisions:** -- Merged 4 inbox files into `.squad/decisions.md` (see log below) - ---- - -## Decisions Merged - -- `gandalf-auth0-role-mapping.md` ✅ -- `legolas-nav-menu.md` ✅ -- `boromir-atlas-connection.md` ✅ -- `copilot-directive-2026-03-17T17-38.md` ✅ - -**Deduplication:** No duplicates found across merged decisions. diff --git a/.squad/log/2026-03-19T15-44-51Z-buildinfo-fix.md b/.squad/log/2026-03-19T15-44-51Z-buildinfo-fix.md deleted file mode 100644 index 373b9d4..0000000 --- a/.squad/log/2026-03-19T15-44-51Z-buildinfo-fix.md +++ /dev/null @@ -1,16 +0,0 @@ -# Session Log: BuildInfo Generation Fix - -**Timestamp:** 2026-03-19T15:44:51Z - -## Work Summary -- Fixed stderr contamination in MSBuild git commands -- Created v0.1.0 git tag -- Verified BuildInfo.g.cs generation and FooterComponent tests -- All agents succeeded; no blockers - -## Agents Involved -1. **Boromir** — Fixed Web.csproj git command stderr redirect -2. **Gimli** — Verified build output and test suite - -## Next -Merge decision inbox, archive old decisions, update agent histories. diff --git a/.squad/log/2026-03-21T15:42:40Z-pr60-review.md b/.squad/log/2026-03-21T15:42:40Z-pr60-review.md deleted file mode 100644 index 04f0f18..0000000 --- a/.squad/log/2026-03-21T15:42:40Z-pr60-review.md +++ /dev/null @@ -1,15 +0,0 @@ -# Session Log — PR #60 Review - -**Timestamp:** 2026-03-21T15:42:40Z -**Topic:** PR #60 MongoDB Connection String Fallback + Cleanup Review - -## Summary - -Three agents (Aragorn, Sam, Gimli) reviewed PR #60 comments. Consensus: - -- **Test Coverage:** BLOCKING — fallback logic lacks unit tests (5 scenarios) -- **Build Log:** Valid but non-blocking — contradictory summary vs. output -- **Squad Files:** Blocking — `.squad/` files should not be in feature branch PR -- **History Date:** Non-blocking documentation hygiene issue - -**Status:** CHANGES REQUESTED before merge diff --git a/.squad/log/2026-03-27T14-05-27Z-playwright-e2e-tests.md b/.squad/log/2026-03-27T14-05-27Z-playwright-e2e-tests.md deleted file mode 100644 index bde4466..0000000 --- a/.squad/log/2026-03-27T14-05-27Z-playwright-e2e-tests.md +++ /dev/null @@ -1,40 +0,0 @@ -# Session Log: AppHost.Tests Playwright E2E tests — 2026-03-27T14:05:27Z - -## Summary -Team successfully created and integrated 10 Playwright E2E test files for the AppHost.Tests project, implementing end-to-end testing infrastructure for the IssueTrackerApp web application. - -## Agents Involved -- **Gimli** (Tester): Created test files, auth state management, theme validation -- **Boromir** (Dependency Manager): Centralized package management, Aspire.Hosting.Testing integration -- **Aragorn** (Infrastructure): Template rewrite, integration test refactoring, project reference fixes - -## Key Deliverables - -### Test Files Created (10 total) -- AuthStateManager.cs — Auth0 login caching via Playwright storage state -- BasePlaywrightTests.cs — Base test class with browser initialization -- LayoutAnonymousTests.cs — Anonymous user layout tests -- LayoutAuthenticatedTests.cs — Authenticated user layout tests -- HomePageTests.cs — Home page navigation and rendering -- DashboardPageTests.cs — Dashboard access and functionality -- NotFoundPageTests.cs — 404 error handling -- IssueIndexPageTests.cs — Issue list page tests -- ThemeToggleTests.cs — Dark/Light/System theme switching -- ColorSchemeTests.cs — Color scheme selection (Blue/Red/Green/Yellow) - -### Build Status -- 0 errors -- 0 warnings -- All tests compile successfully - -### Architecture Decisions -1. **Auth State Pattern:** Single Auth0 login cached to JSON; reused across authenticated tests -2. **Theme Testing:** DOM selectors for `classList.contains('dark')` and `getAttribute('data-theme')` -3. **CPM:** All NuGet versions centralized in Directory.Packages.props -4. **Integration:** Proper ProjectReference paths to Web, Domain, and Persistence assemblies - -## Commits -- Gimli: df31e68 — [PLAYWRIGHT] Created 10 E2E test files for AppHost.Tests - -## Decision Inbox -- 1 new decision: "Playwright Theme DOM Assertions & Auth0 State Pattern" (gimli-playwright-theme-dom.md) diff --git a/.squad/log/2026-03-27T22-09-00Z-pr81-review-merge.md b/.squad/log/2026-03-27T22-09-00Z-pr81-review-merge.md deleted file mode 100644 index 17e20f2..0000000 --- a/.squad/log/2026-03-27T22-09-00Z-pr81-review-merge.md +++ /dev/null @@ -1,31 +0,0 @@ -# Session Log: PR #81 Review & Merge - -**Date:** 2026-03-27T22:09:00Z -**Topic:** GitHub Pages workflow security hardening -**Status:** COMPLETED & MERGED - -## Summary - -PR #81 underwent comprehensive multi-agent review across architecture, DevOps, and security domains. - -### Review Phase - -- **Aragorn (Lead):** REJECTED — path and squad-docs conflicts identified -- **Boromir (DevOps):** REJECTED — path scope, paths filter, and permissions level issues -- **Gandalf (Security):** REJECTED — HIGH severity (SECRETS.md exposure), LOW severity (permissions scope) - -### Fix Phase - -Boromir applied all blockers: -1. Scoped GitHub Pages artifact path from `.` to `docs/` (prevents SECRETS.md exposure) -2. Corrected workflow trigger `paths:` filter configuration -3. Moved permissions from workflow level to job level (defense in depth) -4. Removed `pages: write` from workflow-level permissions block - -### Merge - -PR squash-merged to main after unanimous re-approval. Branch deleted. - -## Key Decision - -**GitHub Pages path must be `docs/` not `.`** — protects sensitive files and source tree from public exposure. diff --git a/.squad/log/2026-03-27T22:42:44Z-issues-77-78-79-80.md b/.squad/log/2026-03-27T22:42:44Z-issues-77-78-79-80.md deleted file mode 100644 index da82eb7..0000000 --- a/.squad/log/2026-03-27T22:42:44Z-issues-77-78-79-80.md +++ /dev/null @@ -1,63 +0,0 @@ -# Session Log: Issues #77–#80 Resolution - -**Timestamp:** 2026-03-27T22:42:44Z -**Session:** Pippin + Legolas Squad Work -**Outcome:** ✅ All 4 issues closed, 2 PRs merged - -## Summary - -Four test/UX issues resolved in a single coordinated squad run: - -### Frontend: Issue #77 (Legolas) - -**Missing `/Account/AccessDenied` page** - -- Auth0 redirects denied users to `/Account/AccessDenied` (ASP.NET Core convention) -- App had no Blazor component at this route; users hit NotFound -- **Fix:** Created `src/Web/Components/Pages/Account/AccessDenied.razor` - - Static, public page with friendly error copy - - `@layout MainLayout` (consistent UX) - - Tailwind `neutral-*` styling -- **PR:** #83 (Approved by Aragorn, Gandalf) -- **Status:** Merged ✅ - -### Test Quality: Issues #78, #79, #80 (Pippin) - -**Three blocking test issues in `AppHost.Tests`** - -1. **#78 — TimeoutException not surfaced** - - `WaitForWebReadyAsync` polling loop let `OperationCanceledException` escape - - Fix: Wrap loop to throw `TimeoutException` on deadline expiry - - Semantics: `OperationCanceledException` = cooperative cancellation; `TimeoutException` = deadline - -2. **#79 — Dashboard enabled in tests** - - `EnvVarTests.cs` was the only test missing `DisableDashboard = true` - - Fix: Add consistent config pattern used by `AspireManager.cs` - - Reason: Prevents Aspire dashboard resource waste in CI - -3. **#80 — Weak heading assertion** - - `text.Should().NotBeNullOrWhiteSpace()` is non-specific (any non-empty string passes) - - Fix: Replace with `text.Should().Be("Admin Dashboard")` (exact match) - - Charter rule: Assertions must be specific - -- **PR:** #84 (Approved by Aragorn, Gimli) -- **Status:** Merged ✅ - -## Team Coordination - -| Member | Role | Action | -|--------|------|--------| -| Pippin | E2E & Aspire Tester | Fixed #78, #79, #80 | -| Legolas | Frontend Developer | Created /Account/AccessDenied page (#77) | -| Aragorn | Tech Lead | Reviewed both PRs, approved | -| Gimli | QA | Reviewed PR #84, approved | -| Gandalf | Wizard | Reviewed PR #83, approved | - -## Decisions - -Two decisions recorded in `.squad/decisions/inbox/`: - -1. `pippin-test-fixes-78-79-80.md` — Test quality fixes, exception semantics, assertion specificity -2. `legolas-access-denied-77.md` — AccessDenied page design, auth flow, UX impact - -Both ready to merge into `decisions.md`. diff --git a/.squad/log/2026-03-29-ralph-pr102-merged.md b/.squad/log/2026-03-29-ralph-pr102-merged.md deleted file mode 100644 index c98e7df..0000000 --- a/.squad/log/2026-03-29-ralph-pr102-merged.md +++ /dev/null @@ -1,11 +0,0 @@ -# Session Log — PR #102 Merged - -**Date:** 2026-03-29 - -**Agent:** Ralph (Work Monitor) - -**Work:** 1 cycle — PR #102 ("style: UI polish — nav, footer, SignalR, dashboard cleanup") passed all CI checks and was merged via squash merge. - -**Board:** 0 open issues, 0 open PRs. Board cleared post-merge. - -**Status:** ✅ Complete diff --git a/.squad/log/2026-03-29T14:58:15Z-ralph-round1.md b/.squad/log/2026-03-29T14:58:15Z-ralph-round1.md deleted file mode 100644 index 621cdd0..0000000 --- a/.squad/log/2026-03-29T14:58:15Z-ralph-round1.md +++ /dev/null @@ -1,15 +0,0 @@ -# Ralph Work-Check Round 1 - -**Timestamp:** 2026-03-29T14:58:15Z -**Coordinator:** Ralph - -## Summary -Scanned team issues and PRs. Found 0 open squad-labeled issues. Identified PR #86 with 2 failing E2E tests (Redis timeout). Routed to Pippin for triage and fix. - -## Findings -- **Open Squad Issues:** 0 -- **Failing PR:** #86 (E2E tests failing due to health-check polling timeout) -- **Action:** Escalated to Pippin (Tester E2E & Aspire) - -## Status -✅ Round 1 complete. Work routed. diff --git a/.squad/log/2026-03-29T15-20-55Z-ralph-round2.md b/.squad/log/2026-03-29T15-20-55Z-ralph-round2.md deleted file mode 100644 index 620d96f..0000000 --- a/.squad/log/2026-03-29T15-20-55Z-ralph-round2.md +++ /dev/null @@ -1,34 +0,0 @@ -# Session Log: Ralph Round 2 — Coordinator - -**Timestamp:** 2026-03-29T15:20:55Z -**Coordinator:** Ralph -**Round:** 2 -**Status:** ✅ Complete - -## Summary - -Ralph analyzed Pippin's theme test fixes and routed the production bug (dual theme system) to Aragorn for architectural consolidation. - -## Inputs - -- **Pippin outcome:** Fixed ThemeToggleTests and ColorSchemeTests (localStorage key from `theme-color-brightness` → `tailwind-color-theme`). Discovered dual theme system conflict in production code. -- **Production issue:** Two coexisting theme systems with different localStorage keys → theme persistence fails on page reload. - -## Routing Decision - -**Dual Theme System Consolidation → Aragorn (Backend Developer)** - -- **Rationale:** Backend developer with domain expertise should own theme system unification -- **Context:** PR #86 introduced new theme components that conflict with existing `ThemeProvider` system -- **Scope:** Consolidate to single theme system, ensure theme preferences persist correctly across page reloads -- **Depends on:** Completion of current theme test fixes (Pippin's work) - -## Decision Created - -Merged Pippin's theme test fix decision into `.squad/decisions.md` with production issue flagged. - -## Next Steps - -1. Aragorn implements theme system consolidation (target: next round) -2. Full E2E validation in CI -3. Archive old decisions if file size exceeds ~20KB after merge diff --git a/.squad/log/2026-03-29T16:55:42Z-boromir-dependabot-merge.md b/.squad/log/2026-03-29T16:55:42Z-boromir-dependabot-merge.md deleted file mode 100644 index c6c8414..0000000 --- a/.squad/log/2026-03-29T16:55:42Z-boromir-dependabot-merge.md +++ /dev/null @@ -1,10 +0,0 @@ -# Session Log — Boromir Dependabot Merge (2026-03-29T16:55:42Z) - -**Agent:** Boromir -**Topic:** Dependabot PR #87 Merge - -## Work Summary -Reviewed and merged Dependabot PR #87 containing 5 GitHub Actions updates. All 19 CI checks passed. Used squash-merge strategy to main branch. - -## Status -✅ Complete — PR merged successfully. diff --git a/.squad/log/2026-03-29T17:03:05Z-footer-text-size.md b/.squad/log/2026-03-29T17:03:05Z-footer-text-size.md deleted file mode 100644 index a7dcbaa..0000000 --- a/.squad/log/2026-03-29T17:03:05Z-footer-text-size.md +++ /dev/null @@ -1,17 +0,0 @@ -# Session Summary: Footer Text Size Unification - -**Date:** 2026-03-29 -**Duration:** Background task (Legolas) - -## Work Completed -Legolas removed `text-xs` and `txt-3xl` typo from FooterComponent.razor. All footer text now uses `text-base` for consistency. - -## Status -✅ Ready for merge - -## Files Changed -- `src/Web/Components/Layout/FooterComponent.razor` -- `src/Web/wwwroot/css/app.css` - -## Decision Recorded -Decision entry merged from inbox: `legolas-footer-text-size.md` diff --git a/.squad/log/2026-03-29T17:04:58Z-signalr-text-size.md b/.squad/log/2026-03-29T17:04:58Z-signalr-text-size.md deleted file mode 100644 index e742e3a..0000000 --- a/.squad/log/2026-03-29T17:04:58Z-signalr-text-size.md +++ /dev/null @@ -1,11 +0,0 @@ -# Session Log: SignalR Label Sizing - -**Timestamp:** 2026-03-29T17:04:58Z -**Agent:** Legolas (Frontend Dev) - -## Work Complete - -Removed `text-xs` from SignalRConnection.razor state label spans. Labels now match nav menu link size (text-base). - -**Files:** `src/Web/Components/Shared/SignalRConnection.razor` - diff --git a/.squad/log/2026-03-29T18:08:58Z-role-claims-fix.md b/.squad/log/2026-03-29T18:08:58Z-role-claims-fix.md deleted file mode 100644 index e0cd7f3..0000000 --- a/.squad/log/2026-03-29T18:08:58Z-role-claims-fix.md +++ /dev/null @@ -1,20 +0,0 @@ -# 2026-03-29T18:08:58Z — Auth0 Role Claims Fix Sprint Complete - -## Summary -Sprint 1–3 complete: Aragorn diagnosed and configured Auth0 namespace, Sam added Pass 3 auto-detect failsafe, Legolas hardened Profile.razor UI. - -## Issues Resolved -- **#88:** Diagnosed Auth0 role claim type (Aragorn) -- **#89:** Config fix—set Auth0:RoleClaimNamespace (Aragorn) -- **#90:** Added Pass 3 auto-detect to Auth0ClaimsTransformation (Sam) -- **#91:** Fixed Profile.razor GetAllRoleClaims to include namespace claim (Legolas) - -## Key Decisions Merged -1. **Aragorn:** Auth0 namespace = `"https://issuetracker.com/roles"` -2. **Sam:** Pass 3 auto-detect scans all claims ending in `/roles` when Passes 1–2 fail -3. **Legolas:** Profile.razor GetAllRoleClaims accepts optional namespace param, belt-and-suspenders - -## Build Status -- All 3 agents: Build clean, tests passing -- Total: 10 new tests (2 NavMenu + 8 ProfileRoles) -- Code changes: appsettings.Development.json, Auth0ClaimsTransformation.cs, Profile.razor, tests diff --git a/.squad/log/2026-03-29T18:47:42Z-adminlayout-fix.md b/.squad/log/2026-03-29T18:47:42Z-adminlayout-fix.md deleted file mode 100644 index 5fff395..0000000 --- a/.squad/log/2026-03-29T18:47:42Z-adminlayout-fix.md +++ /dev/null @@ -1,27 +0,0 @@ -# Session Log — AdminPageLayout Sprint 2 - -**Timestamp:** 2026-03-29T18:47:42Z -**Branch:** squad/90-auth0-claims-pass3-auto-detect - -## Sprint Summary - -**Milestone:** AdminPageLayout component guardrails and test coverage -**Team:** Legolas (UI) + Gimli (Tests) - -### Deliverables -1. ✅ AdminPageLayout.razor: Added warning comment (Legolas) -2. ✅ AdminPageLayoutTests.cs: 14 bUnit tests with reflection guards (Gimli) - -### Key Outcomes -- Component usage contract now explicit: `` only, never `@layout` -- Reflection-based guard prevents accidental `LayoutComponentBase` inheritance -- Build clean, all tests passing - -### Build & Test Results -- Build: ✅ Clean -- Tests: ✅ 14/14 passing -- No regressions - -### Artifacts -- Orchestration logs: legolas-adminlayout.md, gimli-adminlayout.md -- Test file: AdminPageLayoutTests.cs (14 tests, 100% pass rate) diff --git a/.squad/log/2026-03-29T21-49-00Z-pr-review-process.md b/.squad/log/2026-03-29T21-49-00Z-pr-review-process.md deleted file mode 100644 index b0521bb..0000000 --- a/.squad/log/2026-03-29T21-49-00Z-pr-review-process.md +++ /dev/null @@ -1,7 +0,0 @@ -# Session: Formal PR Review Process Implementation - -**Date:** 2026-03-29T21:49:00Z -**Agents:** Aragorn (Lead), Boromir (DevOps) -**Requested by:** Matthew Paulosky - -Aragorn and Boromir implemented a complete formal PR review process. Aragorn established ceremonies (PR Review Gate, CHANGES_REQUESTED handling with lockout, conflict resolution), updated routing logic to track 4 new PR state signals (CHANGES_REQUESTED, CONFLICTED, CI FAILURE, ready-for-review), and created a PR template with domain-driven reviewer assignment. Ralph's charter was updated with pre-review and pre-merge gate tables to enforce CI green + MERGEABLE before review and APPROVED + CI still green before merge. Boromir fixed the CI workflow stub to run real dotnet builds, created CODEOWNERS for auto-review routing, and enabled branch protection on main with 1 required review + build check + squash-only merges. Both decisions documented in inbox. diff --git a/.squad/log/2026-04-01T17:15:15Z-ralph-ci-fix.md b/.squad/log/2026-04-01T17:15:15Z-ralph-ci-fix.md deleted file mode 100644 index 8cd683f..0000000 --- a/.squad/log/2026-04-01T17:15:15Z-ralph-ci-fix.md +++ /dev/null @@ -1,18 +0,0 @@ -# Session: Ralph CI Fix — PR #160 Architecture.Tests - -## Summary -Ralph (work monitor) activated by mpaulosky to scan the board and diagnose CI failure in PR #160. Identified Architecture.Tests failure caused by `AuditLogRepository` missing `IRepository` interface implementation. Local commit `ad6a79f` already contained the fix (added `Repository` base class + explicit `IRepository` interface). Fix pushed to `origin/squad/133-mediatr-admin-handlers`. All 40 pre-push tests passed. - -## Work -- **Activation:** Ralph spawn triggered by mpaulosky for board scan -- **Issue:** PR #160 — Architecture.Tests CI failure on Architecture layer boundaries -- **Root Cause:** `AuditLogRepository` did not implement `IRepository` interface; Architecture tests enforce this boundary -- **Resolution:** Local commit `ad6a79f` already fixed via: - - Added `Repository` base class inheritance - - Explicit `IRepository` interface implementation -- **Action Taken:** Pushed `ad6a79f` to `origin/squad/133-mediatr-admin-handlers` -- **Validation:** All 40 pre-push tests passed successfully - -## Next Steps -- Legolas spawned for issue #136 (/admin/users page scaffold) -- PR #160 CI should now pass on next build diff --git a/.squad/log/2026-04-01T19:49:17Z-blog-catchup-release-notes.md b/.squad/log/2026-04-01T19:49:17Z-blog-catchup-release-notes.md deleted file mode 100644 index 73b5f7e..0000000 --- a/.squad/log/2026-04-01T19:49:17Z-blog-catchup-release-notes.md +++ /dev/null @@ -1,14 +0,0 @@ -# Session Log — Blog Catchup & Release Notes -**Timestamp:** 2026-04-01T19:49:17Z -**Topic:** Blog catchup and release notes documentation - ---- - -## Agents Deployed -- **Bilbo** (Tech Blogger) — wrote missing v0.3.0 and v0.4.0 release blog posts (commit 246099c) -- **Frodo** (Tech Writer) — added Release Notes section to docs/index.html (commit 5a6f38b) - ---- - -## Outcome -✅ All tasks completed successfully. Blog backlog cleared, release notes now prominently featured in documentation. diff --git a/.squad/log/2026-04-02-process-docs-review.md b/.squad/log/2026-04-02-process-docs-review.md deleted file mode 100644 index 48c56a4..0000000 --- a/.squad/log/2026-04-02-process-docs-review.md +++ /dev/null @@ -1,26 +0,0 @@ -# Session Log — Team Process & Documentation Optimisation -**Date:** 2026-04-02 -**Session type:** Team-wide review - -## Summary - -Conducted full squad process and documentation review after Sprint 5 (Admin User Management) and Sprint 6 (Labels Feature). Four agents worked in parallel. - -## Work Done - -- **Scribe:** decisions.md archived (118 lines removed); decisions-archive.md created; agent histories summarized (Gimli 974→67, Legolas 809→68, Sam 761→70, Gandalf 371→67 lines) -- **Aragorn:** ceremonies.md enhanced (Sprint Review + Issue Grooming); routing.md updated (5 new signals); 2 new skills (auth0-management-api, labels-feature-patterns) -- **Frodo:** Full docs accuracy audit — README, CONTRIBUTING, docs/index.html, docs/blog/index.md — all verified accurate, no changes needed -- **Gandalf:** 3 security routing signals added; auth0-management-security skill created; 1 MEDIUM finding filed (audit log for role assign/revoke) - -## PRs Merged - -- #186 squad/scribe-memory-sweep -- #185 squad/frodo-docs-audit-2026-04-02 -- #183 squad/process-review-2026-04-02 -- #184 squad/gandalf-security-review-2026-04-02 - -## Identity Updates (this session) - -- identity/now.md — updated to v0.6.0 state -- identity/wisdom.md — populated with 10 patterns from 6 sprints diff --git a/.squad/orchestration-log/2025-03-21T15-05-sam.md b/.squad/orchestration-log/2025-03-21T15-05-sam.md deleted file mode 100644 index 9cfb549..0000000 --- a/.squad/orchestration-log/2025-03-21T15-05-sam.md +++ /dev/null @@ -1,44 +0,0 @@ -# Orchestration Log: Sam (Backend Dev) - -**Timestamp:** 2025-03-21T15:05:00Z -**Agent:** Sam (Backend Developer) -**Task:** Fix MongoDB connection string config mismatch - -## Spawn Context - -**Problem:** Web project crashed with `TimeoutException` connecting to `localhost:27017` instead of Atlas. EF Core MongoDB provider reads `MongoDB:ConnectionString` from appsettings.Development.json (hardcoded to localhost), while Aspire injects the real Atlas connection string into `ConnectionStrings:mongodb`. These config paths never intersect. - -**Scope:** -- `src/Persistence.MongoDb/ServiceCollectionExtensions.cs` — Add fallback logic -- `src/Web/appsettings.Development.json` — Clear localhost default - -## Work Completed - -✅ **Added fallback logic in `AddMongoDbPersistence`:** -1. Check if `MongoDB:ConnectionString` is empty or equals `mongodb://localhost:27017` -2. If so, read `ConnectionStrings:mongodb` and overlay it into MongoDB config section -3. Changed `appsettings.Development.json` to use empty string instead of localhost default - -**Priority order:** -- Explicit `MongoDB:ConnectionString` (non-empty, non-localhost) → used as-is -- Empty/localhost default → falls back to `ConnectionStrings:mongodb` (Aspire-injected or user secrets) - -## Outcome - -✅ **SUCCESS** - -**Result:** -- AppHost runs clean — Aspire injects `ConnectionStrings:mongodb` as env var, fallback picks it up -- Standalone + user secrets works — user secret `ConnectionStrings:mongodb` read as fallback -- Explicit config works — non-empty, non-localhost `MongoDB:ConnectionString` takes priority -- Tests unaffected — `Testing` environment skips `AddMongoDBClient`; tests use TestContainers - -**Files Modified:** -- `src/Persistence.MongoDb/ServiceCollectionExtensions.cs` -- `src/Web/appsettings.Development.json` - -**Pattern Established:** When two config systems disagree (Aspire vs raw appsettings), bridge them at the DI registration layer using configuration overlay before binding Options. - -## Status - -🟢 **Complete** — Ready for merge diff --git a/.squad/orchestration-log/2025-03-29T08-33-36Z-pr86-merged.md b/.squad/orchestration-log/2025-03-29T08-33-36Z-pr86-merged.md deleted file mode 100644 index 9153d22..0000000 --- a/.squad/orchestration-log/2025-03-29T08-33-36Z-pr86-merged.md +++ /dev/null @@ -1,33 +0,0 @@ -# PR #86 Merge Event — Orchestration Log - -**Timestamp:** 2025-03-29T08:33:36Z -**Event:** PR #86 merged into main (squash commit) -**Merge Status:** Complete — all 23 CI checks passed -**E2E Tests:** 40/40 passed - -## Agents Involved -- **Ralph**: Identified 2 failing Aspire+Playwright E2E tests in PR #86 -- **Pippin**: Fixed test startup polling (/health → /alive) and updated theme localStorage key assertions -- **Aragorn**: Resolved dual theme system conflict (removed theme-manager.js, unified to themeManager+tailwind-color-theme) -- **Copilot CLI**: Orchestrated the full session - -## PR Summary -**Title:** fix(web): fix 13 E2E test failures + Issues page bugs + accessibility -**Branch:** squad/86-fix-failing-tests-and-web-razor-pages -**Merge Strategy:** Squash -**Base:** main - -### Changes -- E2E test fixes: polling, theme assertions, health check endpoints -- Theme system unification (removed dual-management conflict) -- Issues page bug fixes -- Accessibility improvements - -## Board Status -✅ **Board is clear** — no blocking issues -✅ **All CI checks passed** (23/23) -✅ **All E2E tests passed** (40/40) - -## Next Steps -- Deployment can proceed -- Session artifacts documented in session log diff --git a/.squad/orchestration-log/2026-03-17T14-30-00Z-aragorn.md b/.squad/orchestration-log/2026-03-17T14-30-00Z-aragorn.md deleted file mode 100644 index f917299..0000000 --- a/.squad/orchestration-log/2026-03-17T14-30-00Z-aragorn.md +++ /dev/null @@ -1,55 +0,0 @@ -# Orchestration Log: Aragorn - -**Timestamp:** 2026-03-17T14:30:00Z -**Agent:** Aragorn (background, claude-sonnet-4.5) -**Status:** ✅ COMPLETED - ---- - -## Mandate - -Review and commit 94 modified files for formatting cleanup, GlobalUsings reorganization, and line ending normalization. - ---- - -## Execution Summary - -### Work Completed - -1. **Formatting Cleanup (94 files)** - - Applied .editorconfig rules across entire codebase - - Normalized indentation (spaces → tabs where applicable) - - Fixed line ending inconsistencies (CRLF → LF per .editorconfig) - - Trailing whitespace removal - -2. **GlobalUsings Reorganization** - - Centralized `using` statements in `GlobalUsings.cs` files per project - - Removed redundant `using` declarations from source files - - Alphabetized and deduplicated imports - -3. **Line Ending Normalization** - - Applied LF line endings across all text files per .editorconfig - - Ensured charset UTF-8 consistency - -### Staging & Commit - -- **Files Modified:** 94 -- **Branch:** main (local) -- **Commit Message:** Applied .editorconfig formatting rules, reorganized GlobalUsings, normalized line endings -- **Commit Hash:** Created and verified - ---- - -## Outcome - -✅ **All 94 files successfully reviewed, formatted, and committed to local main branch.** - -No blocking issues encountered. Formatting changes are non-functional and improve code consistency across the repository. - ---- - -## Notes for Team - -- Commit is local; await merge confirmation from team lead -- No production code logic changed — purely mechanical cleanup -- .editorconfig rules now enforced across codebase diff --git a/.squad/orchestration-log/2026-03-17T14-30-00Z-gimli.md b/.squad/orchestration-log/2026-03-17T14-30-00Z-gimli.md deleted file mode 100644 index 51214aa..0000000 --- a/.squad/orchestration-log/2026-03-17T14-30-00Z-gimli.md +++ /dev/null @@ -1,65 +0,0 @@ -# Orchestration Log: Gimli - -**Timestamp:** 2026-03-17T14:30:00Z -**Agent:** Gimli (background, claude-sonnet-4.5) -**Status:** ⚠️ PARTIAL SUCCESS - ---- - -## Mandate - -Diagnose and optimize slow/hanging bUnit test suite (595 tests). Investigate and fix 2 failing delete tests in DetailsPageTests. - ---- - -## Execution Summary - -### Work Completed - -1. **bUnit Test Suite Diagnosis** - - Root cause identified: Tests hang when running full suite together (~2+ minutes) - - Individual test projects run quickly (1-7 seconds) - - Issue traced to BunitContext state conflicts during parallel execution - -2. **Parallelism Configuration** - - Created `tests/Web.Tests.Bunit/xunit.runner.json` - - Configured: `parallelizeTestCollections: false`, `maxParallelThreads: 4` - - Rationale: Reduces resource contention; bUnit test context requires isolated state per test - -3. **Failing Delete Tests Investigation** - - **Failing Tests:** - - `DetailsPageTests.Details_DeleteExecutionNavigatesToIndex` - - `DetailsPageTests.Details_DeleteFailureShowsError` - - **Root Cause:** EventCallback chain in DeleteConfirmationModal not completing - - Modal renders correctly; confirm button detected; EventCallback works in isolation - - **Blocker:** Callback not invoked when modal embedded in Details page - -### Outstanding Issues - -1. **Two Delete Tests Still Failing** - - EventCallback not firing in nested component context - - Requires investigation of: - - bUnit framework limitations with cascading EventCallbacks - - Production code issue in Details page event handling - - Test setup issue with AuthenticationStateProvider state - -2. **Full Suite Execution Still Slow** - - Parallelism config reduces but doesn't eliminate slowness - - Likely root cause: SignalRClientService or resource leak during test disposal - - Workaround: Run tests in smaller groups by filter - ---- - -## Handoff - -✅ **xunit.runner.json created and committed** -⚠️ **Delete tests require further investigation (Legolas in progress)** -⏳ **Full suite optimization deferred pending test fix** - ---- - -## Notes for Team - -- Parallelism config is production-ready and reduces test execution overhead -- Delete test failure may reveal underlying issue causing suite slowness -- Temporary workaround: Filter tests by FullyQualifiedName to run subsets diff --git a/.squad/orchestration-log/2026-03-17T17-26-00Z-sam.md b/.squad/orchestration-log/2026-03-17T17-26-00Z-sam.md deleted file mode 100644 index f6e3a98..0000000 --- a/.squad/orchestration-log/2026-03-17T17-26-00Z-sam.md +++ /dev/null @@ -1,48 +0,0 @@ -# Agent Orchestration Log: Sam - -**Timestamp:** 2026-03-17T17:26:00Z -**Agent:** Sam (Backend Developer) -**Task:** Fix DI lifetime mismatches in ServiceCollectionExtensions.cs and BulkOperationBackgroundService.cs - -## Summary - -Fixed two startup-blocking DI validation failures: - -1. **DbContextFactory lifetime conflict** → Registered factory as scoped to match DbContext options -2. **BackgroundService scoped injection** → Removed unused `INotificationService` field from constructor - -## Outcome - -✅ **SUCCESS** -- Both fixes applied -- Build passes -- Startup validation errors resolved - -## Files Modified - -- `src/Persistence.MongoDb/ServiceCollectionExtensions.cs` -- `src/Web/Services/BulkOperationBackgroundService.cs` - -## Decision - -Decision written to `.squad/decisions/inbox/sam-di-lifetime-fix.md` - -## Rationale - -**Fix 1 (Scoped DbContextFactory):** -- `AddDbContext` registers options as scoped -- `AddDbContextFactory` defaults to singleton -- Singleton cannot consume scoped options → DI validation error -- Solution: Explicitly set `lifetime: ServiceLifetime.Scoped` on factory registration - -**Fix 2 (Remove scoped from singleton):** -- `BulkOperationBackgroundService` is singleton -- Constructor was injecting `INotificationService` (scoped) -- Field was never used in any method -- Service already resolves scoped deps via `IServiceScopeFactory` per-operation -- Solution: Remove unused dependency - -## Team Rules Established - -1. When combining `AddDbContext` + `AddDbContextFactory`, always align lifetimes explicitly -2. Background services (singletons) must never inject scoped services directly — always use `IServiceScopeFactory` diff --git a/.squad/orchestration-log/2026-03-17T18-54-25Z-gandalf.md b/.squad/orchestration-log/2026-03-17T18-54-25Z-gandalf.md deleted file mode 100644 index 0a8fc34..0000000 --- a/.squad/orchestration-log/2026-03-17T18-54-25Z-gandalf.md +++ /dev/null @@ -1,90 +0,0 @@ -# Orchestration: Gandalf — Auth0 Role Claim Mapping (2026-03-17T18:54:25Z) - -**Agent:** Gandalf (Security Officer) -**Model:** claude-sonnet-4.5 -**Mode:** background -**Duration:** Completed - ---- - -## Mission - -Fix Auth0 role-based authorization issue where authenticated users with Admin/User roles received "Access Denied" on protected pages. - ---- - -## Work Completed - -### Root Cause Analysis -- Auth0 sends roles in custom namespaced claim (e.g., `https://issuetracker.com/roles`) -- ASP.NET Core's `RequireRole()` policy checks for standard `ClaimTypes.Role` claim type -- Without mapping, roles exist in JWT but aren't recognized by authorization policies - -### Implementation -1. **Created** `src/Web/Auth/Auth0ClaimsTransformation.cs` - - IClaimsTransformation service - - Maps Auth0 custom role claims to standard ClaimTypes.Role - - Handles multiple role formats: JSON arrays, CSV, single values - - Includes idempotency check and comprehensive logging - -2. **Extended** `src/Web/Auth/Auth0Options.cs` - - Added `RoleClaimNamespace` property (configurable via user secrets) - - Namespace must match Auth0 tenant configuration - -3. **Updated** `src/Web/Program.cs` - - Registered claims transformation as scoped service in auth pipeline - -4. **Updated** `src/Web/appsettings.json` - - Added `RoleClaimNamespace` configuration field with placeholder - ---- - -## Outcome - -✅ **SUCCESS** — Build passes, role-based authorization mechanism now in place. - -### Configuration Required -Developers must set `Auth0:RoleClaimNamespace` in user secrets: -```bash -dotnet user-secrets set "Auth0:RoleClaimNamespace" "https://issuetracker.com/roles" -``` - -### Security Verification -- ✅ No secrets in source code -- ✅ Transformation idempotent (prevents duplicate claims) -- ✅ Audit logging included -- ✅ Only processes authenticated JWT claims - ---- - -## Deliverables - -**Files Created:** -- `.squad/decisions/inbox/gandalf-auth0-role-mapping.md` → merged to decisions.md - -**Files Modified (in src/):** -- `Web/Auth/Auth0ClaimsTransformation.cs` (new) -- `Web/Auth/Auth0Options.cs` (RoleClaimNamespace) -- `Web/Program.cs` (service registration) -- `Web/appsettings.json` (configuration field) - -**Tests:** -- Manual verification with Auth0 test users (pending environment setup) - ---- - -## Related Decisions - -- **Auth0 Authentication Implementation** (2026-03-12): Initial auth setup -- **Auth0 Role Claim Mapping** (2026-03-19): This decision - ---- - -## Team Impact - -**For Sam (Backend):** Claims transformation follows standard ASP.NET Core pattern; integrates cleanly with DI. - -**For Legolas (Frontend):** NavMenuComponent now works with properly mapped roles; authorization policies function as intended. - -**For Matthew (Project Lead):** Configure `Auth0:RoleClaimNamespace` in user secrets to activate role-based access. - diff --git a/.squad/orchestration-log/2026-03-17T18-54-25Z-legolas.md b/.squad/orchestration-log/2026-03-17T18-54-25Z-legolas.md deleted file mode 100644 index b96a12e..0000000 --- a/.squad/orchestration-log/2026-03-17T18-54-25Z-legolas.md +++ /dev/null @@ -1,91 +0,0 @@ -# Orchestration: Legolas — Navigation Menu & Landing Page (2026-03-17T18:54:25Z) - -**Agent:** Legolas (Frontend Developer) -**Model:** claude-sonnet-4.5 -**Mode:** background -**Duration:** Completed - ---- - -## Mission - -Implement role-based navigation UI and redesign landing page to support authenticated/unauthenticated user states. - ---- - -## Work Completed - -### Navigation Component -1. **Created** `src/Web/Components/Layout/NavMenuComponent.razor` - - Fixed 256px width left sidebar (visible when authenticated) - - Role-based navigation with nested AuthorizeView components - - Separated user-level items (Home, Dashboard, Issues) from admin items (Admin Dashboard, Categories, Statuses, Analytics) - - Emoji icons for visual distinction - - Dark mode support via TailwindCSS - -### Layout Integration -1. **Updated** `src/Web/Components/Layout/MainLayout.razor` - - Integrated NavMenuComponent within AuthorizeView - - Responsive flex layout: header (top) + sidebar (left) + content (right) - - Clean separation of authenticated vs unauthenticated UI - -### Landing Page Redesign -1. **Updated** `src/Web/Components/Pages/Home.razor` - - Dual-state layout: authenticated and unauthenticated views - - Unauthenticated: Welcome message with call-to-action to login - - Authenticated: Brief dashboard preview with quick links - - Proper semantic HTML and accessibility markers - ---- - -## Outcome - -✅ **SUCCESS** — Build passes, navigation and landing page now functional. - -### Features Delivered -- Users can now navigate between authenticated pages -- Clear separation between user and admin features -- Responsive sidebar layout -- Support for future navigation expansion - -### Architecture Quality -- Follows Blazor component conventions -- Uses cascading parameters correctly (avoids context conflicts) -- Authorization policies properly enforced -- No icon library dependencies (emoji-based) - ---- - -## Deliverables - -**Files Created:** -- `.squad/decisions/inbox/legolas-nav-menu.md` → merged to decisions.md -- `src/Web/Components/Layout/NavMenuComponent.razor` (new) - -**Files Modified (in src/):** -- `Web/Components/Layout/MainLayout.razor` (integration) -- `Web/Components/Pages/Home.razor` (dual-state landing) - -**Tests:** -- Build verification passed -- Manual navigation testing in Blazor app - ---- - -## Related Decisions - -- **Navigation Menu Architecture** (2026-03-13): Initial design -- **bUnit Modal Button Selector Pattern** (2026-03-15): Related to component testing - ---- - -## Team Impact - -**For Gandalf (Security):** Navigation respects authorization policies; roles from claims transformation work correctly with menu visibility. - -**For Sam (Backend):** Navigation integrates cleanly with existing authorization policies and DI setup. - -**For Gimli (QA):** Navigation component ready for bUnit test coverage; recommend scoping modal/dialog buttons per established pattern. - -**For Matthew (Project Lead):** Users can now see and navigate authenticated application features. - diff --git a/.squad/orchestration-log/2026-03-18-gimli.md b/.squad/orchestration-log/2026-03-18-gimli.md deleted file mode 100644 index cab7aa0..0000000 --- a/.squad/orchestration-log/2026-03-18-gimli.md +++ /dev/null @@ -1,33 +0,0 @@ -# Orchestration Log: Gimli (Tester) — Post-PR#57 Improvements - -**Timestamp:** 2026-03-18T13-30-01Z - -## Tasks Completed - -### 1. Test Fixes — 4 Broken Tests -- **File:** `tests/Web.Tests.Bunit/Layout/LayoutComponentTests.cs` - - Fixed: Constructor mismatch in LayoutComponent test setup - -- **File:** `tests/Web.Tests.Bunit/Shared/SharedComponentTests.cs` - - Fixed: CSS class assertions updated from `bg-gray-*` to `bg-primary-*` - - Fixed: SignalR indicator structure assertions (removed `.fixed` and floating card selectors) - - Fixed: SignalR text assertions updated to match inline header component - -### 2. Test Coverage Additions — 9 New Tests -- **File:** `tests/Domain.Tests/Features/Issues/CreateIssueCommandHandlerTests.cs` - - Added 5 new tests for status repository mocking patterns - - Coverage: Default status not found, status found in DB, fallback behavior - -- **File:** `tests/Domain.Tests/Mappers/StatusMapperTests.cs` - - Added 4 new tests for `StatusMapper.ToInfo(Status?)` overload - - Coverage: Null input, valid status mapping, edge cases - -### 3. Test Suite Status -✅ All 1479 tests passing -- 4 broken tests fixed -- 9 new tests added -- No regressions - -## Notes -- bUnit tests now scoped to query theme-aware classes within appropriate component contexts -- Mocking patterns for status repository established as team standard for future CreateIssueCommandHandler tests diff --git a/.squad/orchestration-log/2026-03-18-legolas.md b/.squad/orchestration-log/2026-03-18-legolas.md deleted file mode 100644 index 52b435b..0000000 --- a/.squad/orchestration-log/2026-03-18-legolas.md +++ /dev/null @@ -1,32 +0,0 @@ -# Orchestration Log: Legolas (Frontend) — Post-PR#57 Improvements - -**Timestamp:** 2026-03-18T13-30-01Z - -## Tasks Completed - -### 1. Theme-Aware Layout Backgrounds -- **Files:** `src/Web/Components/Layout/MainLayout.razor`, `src/Web/Styles/app.css` -- **Change:** Updated MainLayout background from static `bg-gray-50` to `bg-primary-950` (light mode) / `bg-primary-50` (dark mode) -- **Impact:** Layout now responds to selected color theme (blue/red/green/yellow) - -### 2. Header Background Update -- **File:** `src/Web/Components/Layout/MainLayout.razor` -- **Change:** Header uses `bg-primary-900` (light) / `bg-primary-100` (dark) -- **Impact:** Subtle header tint without overwhelming content - -### 3. SignalR Indicator Relocation -- **Files:** `src/Web/Components/Shared/SignalRConnection.razor`, `src/Web/Components/Layout/MainLayout.razor` -- **Change:** Moved `` from fixed bottom-right floating card to inline in header's right-side utility bar (after LoginDisplay) -- **Impact:** Less intrusive, immediately visible, consistent with SaaS UI patterns - -### 4. Dark Mode CSS Update -- **File:** `src/Web/Styles/app.css` -- **Change:** Updated `.dark body` CSS rule to use `var(--color-primary-50)` instead of hardcoded `#111827` -- **Impact:** Dark mode backgrounds now theme-aware - -## Test Status -CSS and layout assertions updated and passing. - -## Notes -- No backend changes required — SignalRConnection still uses same `SignalRClientService` -- Screenshots in documentation may need refresh to show new themed backgrounds diff --git a/.squad/orchestration-log/2026-03-18-sam.md b/.squad/orchestration-log/2026-03-18-sam.md deleted file mode 100644 index cd6f0cd..0000000 --- a/.squad/orchestration-log/2026-03-18-sam.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration Log: Sam (Backend) — Post-PR#57 Improvements - -**Timestamp:** 2026-03-18T13-30-01Z - -## Tasks Completed - -### 1. Status Repository Injection -- **File:** `src/Domain/Features/Issues/Commands/CreateIssueCommand.cs` -- **Change:** Injected `IRepository` into `CreateIssueCommandHandler` -- **Impact:** Resolved "Open" status from MongoDB instead of hardcoding `ObjectId.Empty` - -### 2. StatusMapper Overload -- **File:** `src/Domain/Mappers/StatusMapper.cs` -- **Change:** Added `StatusMapper.ToInfo(Status?)` overload for direct model-to-value-object conversion -- **Impact:** Enables seamless status mapping in command handlers - -### 3. Test Updates -- **File:** `tests/Domain.Tests/Features/Issues/CreateIssueCommandHandlerTests.cs` -- **File:** `tests/Domain.Tests/Mappers/StatusMapperTests.cs` -- **Change:** Updated test mocking patterns to verify status repository lookup with fallback behavior -- **Status:** All tests passing - -## Build Status -✅ Build clean, no compilation errors. - -## Notes -- Fallback behavior ensures backward compatibility if Status collection is empty -- Requires "Open" status seed data in database for production diff --git a/.squad/orchestration-log/2026-03-19T15-44-51Z-boromir.md b/.squad/orchestration-log/2026-03-19T15-44-51Z-boromir.md deleted file mode 100644 index 57b7108..0000000 --- a/.squad/orchestration-log/2026-03-19T15-44-51Z-boromir.md +++ /dev/null @@ -1,19 +0,0 @@ -# Orchestration Log: Boromir (DevOps) - -**Timestamp:** 2026-03-19T15:44:51Z -**Mode:** background -**Status:** SUCCESS - -## Task -Fix git describe stderr leak in Web.csproj + create v0.1.0 git tag - -## Outcome -- Added `2>/dev/null` to git describe command: `git describe --tags --abbrev=0 2>/dev/null` -- Added `2>/dev/null` to git rev-parse command: `git rev-parse --short HEAD 2>/dev/null` -- Created git tag: `v0.1.0` -- Root cause: stderr contamination in MSBuild ExecWithOutput task was breaking fallback logic - -## Impact -- BuildInfo.g.cs now generates clean build metadata -- Footer displays correct version instead of error text -- Fallback to v0.0.0 works for repos without tags diff --git a/.squad/orchestration-log/2026-03-19T15-44-51Z-gimli.md b/.squad/orchestration-log/2026-03-19T15-44-51Z-gimli.md deleted file mode 100644 index 399ec05..0000000 --- a/.squad/orchestration-log/2026-03-19T15-44-51Z-gimli.md +++ /dev/null @@ -1,20 +0,0 @@ -# Orchestration Log: Gimli (Tester) - -**Timestamp:** 2026-03-19T15:44:51Z -**Mode:** background -**Status:** SUCCESS - -## Task -Verify BuildInfo.g.cs generation + run FooterComponent tests - -## Outcome -- Clean build passed -- BuildInfo.g.cs generated successfully - - Version: `v0.1.0` - - Commit: `e4874a8` -- All 11 FooterComponent tests passed - -## Impact -- Build metadata generation pipeline verified end-to-end -- Footer component correctly displays generated build info -- No regressions in component test suite diff --git a/.squad/orchestration-log/2026-03-24T14_15_51Z-aragorn.md b/.squad/orchestration-log/2026-03-24T14_15_51Z-aragorn.md deleted file mode 100644 index 8b05f58..0000000 --- a/.squad/orchestration-log/2026-03-24T14_15_51Z-aragorn.md +++ /dev/null @@ -1,22 +0,0 @@ -# Orchestration Log: Aragorn (Lead) - -**Timestamp:** 2026-03-24T14:15:51Z -**Mode:** background -**Task:** Code review of uncommitted changes (50 files) - -## Outcome -**Status:** APPROVED - -## Summary -Reviewed all uncommitted working directory changes spanning 50 files. Changes include NuGet updates, CSS migration (gray-* → neutral-*), ThemeToggle extraction, and test updates. - -## Findings -- ✅ Architecture sound and complete -- ✅ CSS migration verified (zero remaining gray-* references) -- ✅ ThemeToggle extraction follows Blazor patterns -- ✅ Dead CSS cleanup applied -- ⚠️ ACTION REQUIRED: Add .agents/, .claude/, .junie/, skills-lock.json to .gitignore -- ⚠️ DECISION PENDING: docs/research/ disposition - -## Details -Full review in decisions.md diff --git a/.squad/orchestration-log/2026-03-24T14_15_51Z-gimli.md b/.squad/orchestration-log/2026-03-24T14_15_51Z-gimli.md deleted file mode 100644 index de926ce..0000000 --- a/.squad/orchestration-log/2026-03-24T14_15_51Z-gimli.md +++ /dev/null @@ -1,23 +0,0 @@ -# Orchestration Log: Gimli (Tester) - -**Timestamp:** 2026-03-24T14:15:51Z -**Mode:** background -**Task:** Run full test suite - -## Outcome -**Status:** PASS - -## Summary -Full test suite passed. All 1,477 tests executed successfully across 6 projects. - -## Test Results -Architecture.Tests: 43 PASS -Domain.Tests: 354 PASS -Persistence.AzureStorage.Tests: 33 PASS -Persistence.MongoDb.Tests: 77 PASS -Web.Tests: 348 PASS -Web.Tests.Bunit: 622 PASS -Total: 1,477 PASS - -## Notes -No environment issues. Ready for commit. diff --git a/.squad/orchestration-log/2026-03-27T22-08-46Z-aragorn-pr81-r2.md b/.squad/orchestration-log/2026-03-27T22-08-46Z-aragorn-pr81-r2.md deleted file mode 100644 index b1da09c..0000000 --- a/.squad/orchestration-log/2026-03-27T22-08-46Z-aragorn-pr81-r2.md +++ /dev/null @@ -1,15 +0,0 @@ -# Orchestration: aragorn-pr81-r2 - -**Agent:** Aragorn (Lead Developer) -**Task:** Lead review of PR #81 -**Status:** REJECTED -**Timestamp:** 2026-03-27T22:08:46Z - -## Blockers - -1. **path**: GitHub Pages artifact path exposes SECRETS.md -2. **squad-docs conflict**: Permissions scope mismatch (workflow vs job level) - -## Next Steps - -Fixes applied by Boromir in PR branch. Awaiting re-review. diff --git a/.squad/orchestration-log/2026-03-27T22-08-47Z-boromir-pr81-r2.md b/.squad/orchestration-log/2026-03-27T22-08-47Z-boromir-pr81-r2.md deleted file mode 100644 index d6c83a5..0000000 --- a/.squad/orchestration-log/2026-03-27T22-08-47Z-boromir-pr81-r2.md +++ /dev/null @@ -1,16 +0,0 @@ -# Orchestration: boromir-pr81-r2 - -**Agent:** Boromir (DevOps) -**Task:** DevOps review of PR #81 -**Status:** REJECTED -**Timestamp:** 2026-03-27T22:08:47Z - -## Blockers - -1. **path**: Artifact path `docs/` required instead of `.` -2. **paths filter**: Workflow trigger paths misconfigured -3. **squad-docs conflict**: Job-level permissions needed, workflow-level removed - -## Resolution - -All blockers resolved in follow-up commit. PR re-approved and merged. diff --git a/.squad/orchestration-log/2026-03-27T22-08-48Z-gandalf-pr81-review.md b/.squad/orchestration-log/2026-03-27T22-08-48Z-gandalf-pr81-review.md deleted file mode 100644 index 6bacefe..0000000 --- a/.squad/orchestration-log/2026-03-27T22-08-48Z-gandalf-pr81-review.md +++ /dev/null @@ -1,20 +0,0 @@ -# Orchestration: gandalf-pr81-review - -**Agent:** Gandalf (Security) -**Task:** Security review of PR #81 -**Status:** REJECTED -**Timestamp:** 2026-03-27T22:08:48Z - -## Issues - -### HIGH - -- **path exposes SECRETS.md**: GitHub Pages workflow artifact path set to `.` (root), publishing full repository including sensitive files to public endpoint - -### LOW - -- **permissions scope**: Permissions assigned at workflow level instead of job level (defense in depth) - -## Resolution - -Boromir applied fixes: path scoped to `docs/`, permissions moved to job level. PR re-reviewed and approved. diff --git a/.squad/orchestration-log/2026-03-27T22-08-49Z-boromir-pr81-fix.md b/.squad/orchestration-log/2026-03-27T22-08-49Z-boromir-pr81-fix.md deleted file mode 100644 index 2833b10..0000000 --- a/.squad/orchestration-log/2026-03-27T22-08-49Z-boromir-pr81-fix.md +++ /dev/null @@ -1,17 +0,0 @@ -# Orchestration: boromir-pr81-fix - -**Agent:** Boromir (DevOps) -**Task:** Apply all fixes to mpaulosky-patch-1 -**Status:** COMPLETED -**Timestamp:** 2026-03-27T22:08:49Z - -## Fixes Applied - -1. **path → docs**: Changed artifact path from `.` to `docs/` in GitHub Pages workflow -2. **paths filter**: Corrected workflow trigger paths configuration -3. **job-level permissions**: Moved permissions from workflow scope to job scope -4. **squad-docs.yml**: Stripped `pages: write` from workflow-level permissions - -## Result - -All blockers resolved. PR re-approved by Aragorn and Gandalf. Squash-merged to main. diff --git a/.squad/orchestration-log/2026-03-27T22:42:44Z-legolas.md b/.squad/orchestration-log/2026-03-27T22:42:44Z-legolas.md deleted file mode 100644 index 208e9a8..0000000 --- a/.squad/orchestration-log/2026-03-27T22:42:44Z-legolas.md +++ /dev/null @@ -1,31 +0,0 @@ -# Orchestration: Legolas (Frontend Developer) - -**Timestamp:** 2026-03-27T22:42:44Z -**Role:** Frontend Developer -**Status:** ✅ COMPLETE - -## Spawn Tasks - -| Issue | Title | Action | PR | Status | -|-------|-------|--------|----|----| -| #77 | /Account/AccessDenied page missing | Created | #83 | Merged | - -## Work Summary - -Created `src/Web/Components/Pages/Account/AccessDenied.razor`: - -- **Route:** `@page "/Account/AccessDenied"` -- **Layout:** `MainLayout` (consistent with other non-auth pages) -- **Auth:** No `[Authorize]` attribute (user was just denied access) -- **Styling:** Tailwind `neutral-*` palette per charter -- **Copy:** Friendly error message + link to home -- **Impact:** Users denied by Auth0 now see a branded error page instead of NotFound - -## Reviews - -- Approved by: Aragorn, Gandalf -- PR Status: Merged - -## Decision - -Recorded at `.squad/decisions/inbox/legolas-access-denied-77.md`. Context: Auth0 redirects to `/Account/AccessDenied` by convention; app was missing the page, causing 404 UX. diff --git a/.squad/orchestration-log/2026-03-27T22:42:44Z-pippin.md b/.squad/orchestration-log/2026-03-27T22:42:44Z-pippin.md deleted file mode 100644 index 84a703f..0000000 --- a/.squad/orchestration-log/2026-03-27T22:42:44Z-pippin.md +++ /dev/null @@ -1,30 +0,0 @@ -# Orchestration: Pippin (E2E & Aspire Tester) - -**Timestamp:** 2026-03-27T22:42:44Z -**Role:** E2E & Aspire Tester -**Status:** ✅ COMPLETE - -## Spawn Tasks - -| Issue | Title | Action | PR | Status | -|-------|-------|--------|----|----| -| #78 | TimeoutException not surfaced in WaitForWebReadyAsync | Fixed | #84 | Merged | -| #79 | EnvVarTests must set DisableDashboard = true | Fixed | #84 | Merged | -| #80 | Admin dashboard heading assertion too weak | Fixed | #84 | Merged | - -## Work Summary - -Fixed three test-quality issues in `tests/AppHost.Tests/`: - -1. **#78:** `BasePlaywrightTests.cs` → wrapped polling loop to throw `TimeoutException` instead of `OperationCanceledException` on deadline expiry. -2. **#79:** `EnvVarTests.cs` → added `DisableDashboard = true` config pattern used by `AspireManager.cs`. -3. **#80:** `AdminPageTests.cs` → replaced weak `Should().NotBeNullOrWhiteSpace()` with exact `Should().Be("Admin Dashboard")`. - -## Reviews - -- Approved by: Aragorn, Gimli -- PR Status: Merged - -## Decision - -Recorded at `.squad/decisions/inbox/pippin-test-fixes-78-79-80.md`. Details on each fix's rationale (assertion specificity, env var propagation, exception semantics). diff --git a/.squad/orchestration-log/2026-03-29T14:58:15Z-pippin.md b/.squad/orchestration-log/2026-03-29T14:58:15Z-pippin.md deleted file mode 100644 index 9fa0d6e..0000000 --- a/.squad/orchestration-log/2026-03-29T14:58:15Z-pippin.md +++ /dev/null @@ -1,21 +0,0 @@ -# Pippin Orchestration Log - -**Timestamp:** 2026-03-29T14:58:15Z -**Agent:** Pippin (Tester E2E & Aspire) -**Mode:** background - -## Outcome -Fixed flaky CI test failures in PR #86 by switching `WaitForWebHealthyAsync` and `WaitForWebReadyAsync` from polling `/health` to `/alive`. - -## Actions Taken -- Identified root cause of Redis timeout in E2E tests -- Updated health-check endpoints to use `/alive` instead of `/health` -- Committed changes to `squad/86-fix-failing-tests-and-web-razor-pages` -- Pushed branch -- Verified build clean - -## Branch -`squad/86-fix-failing-tests-and-web-razor-pages` - -## Status -✅ Complete diff --git a/.squad/orchestration-log/2026-03-29T15-20-55Z-pippin.md b/.squad/orchestration-log/2026-03-29T15-20-55Z-pippin.md deleted file mode 100644 index bf3977f..0000000 --- a/.squad/orchestration-log/2026-03-29T15-20-55Z-pippin.md +++ /dev/null @@ -1,50 +0,0 @@ -# Orchestration Log: Pippin (Tester) - -**Timestamp:** 2026-03-29T15:20:55Z -**Agent:** Pippin -**Role:** Tester -**Status:** ✅ Complete - -## Outcome - -Fixed ThemeToggleTests and ColorSchemeTests — updated localStorage key assertion from `theme-color-brightness` to `tailwind-color-theme`. - -## Key Findings - -- **Dual theme system conflict discovered** in production code: - - OLD system: `theme.js` + `ThemeProvider.razor.cs` uses key `theme-color-brightness` - - NEW system: `theme-manager.js` + new components use key `tailwind-color-theme` - - Both systems coexist without synchronization → theme preferences don't persist correctly on page reload - -## Actions Taken - -1. Updated test assertions in: - - `tests/AppHost.Tests/Tests/Theme/ThemeToggleTests.cs` (2 tests) - - `tests/AppHost.Tests/Tests/Theme/ColorSchemeTests.cs` (2 tests) -2. Changed all localStorage key checks from `theme-color-brightness` to `tailwind-color-theme` -3. Updated test comments to document the dual system conflict -4. Committed changes: **d7b2b1a** -5. Pushed to origin - -## Production Issue Flagged - -The dual theme system is a **production bug** requiring immediate attention from Aragorn (Backend): -- User theme changes via new components persist to `tailwind-color-theme` -- On page reload, `ThemeProvider` reads from `theme-color-brightness` (stale value) -- Result: Theme preferences don't persist across sessions - -**Recommended Actions (routed to Aragorn):** -- Unify theme persistence to use a single localStorage key -- Ensure all theme components use the same system on page initialization - -## Testing - -- Build: ✅ Succeeded -- Compilation: ✅ No errors -- Full E2E test run: ⏳ Pending Docker/CI validation - ---- - -## Routing - -- **Coordinator Round 2:** Ralph assigned production theme fix to Aragorn for consolidation diff --git a/.squad/orchestration-log/2026-03-29T16:55:42Z-boromir.md b/.squad/orchestration-log/2026-03-29T16:55:42Z-boromir.md deleted file mode 100644 index 9fdf813..0000000 --- a/.squad/orchestration-log/2026-03-29T16:55:42Z-boromir.md +++ /dev/null @@ -1,21 +0,0 @@ -# Orchestration Log — Boromir (2026-03-29T16:55:42Z) - -**Agent:** Boromir (DevOps) -**Model:** claude-haiku-4.5 -**Mode:** background -**Status:** SUCCESS - -## Summary -Reviewed and merged Dependabot PR #87 — bumped 5 GitHub Actions, all 19 CI checks green, squash-merged to main. - -## Work Completed -- ✅ Reviewed PR #87: "build(deps): Bump the all-actions group with 5 updates" -- ✅ Verified all 19 CI checks passed -- ✅ Squash-merged to main with auto-merge flag -- ✅ Confirmed no regressions or merge conflicts - -## Decision Documented -Decision recorded in `.squad/decisions/inbox/boromir-dependabot-merge.md` for inbox merge. - -## Outcome -PR #87 successfully integrated into main branch. GitHub Actions workflows updated to latest compatible versions with improved CI/CD stability and security. diff --git a/.squad/orchestration-log/2026-03-29T17:03:05Z-legolas.md b/.squad/orchestration-log/2026-03-29T17:03:05Z-legolas.md deleted file mode 100644 index 5c1a3b8..0000000 --- a/.squad/orchestration-log/2026-03-29T17:03:05Z-legolas.md +++ /dev/null @@ -1,19 +0,0 @@ -# Legolas — Session 2026-03-29T17:03:05Z - -## Task -Footer component text size cleanup. - -## Changes -- Removed `text-xs` class from inner footer div in `src/Web/Components/Layout/FooterComponent.razor` -- Removed invalid `txt-3xl` typo from version/commit links -- All footer text now defaults to `text-base` matching copyright span - -## Status -✅ COMPLETED - -## Files Modified -- `src/Web/Components/Layout/FooterComponent.razor` -- `src/Web/wwwroot/css/app.css` (CSS-related updates) - -## Notes -Footer component now has consistent text sizing across all elements. diff --git a/.squad/orchestration-log/2026-03-29T17:04:58Z-legolas.md b/.squad/orchestration-log/2026-03-29T17:04:58Z-legolas.md deleted file mode 100644 index 34df889..0000000 --- a/.squad/orchestration-log/2026-03-29T17:04:58Z-legolas.md +++ /dev/null @@ -1,15 +0,0 @@ -# Legolas Session — 2026-03-29T17:04:58Z - -**Role:** Frontend Dev - -## Work Summary - -- **Task:** SignalR connection state labels styling alignment -- **File Modified:** `src/Web/Components/Shared/SignalRConnection.razor` -- **Change:** Removed `text-xs` class from all three state label spans (Live, Connecting, Offline). Labels now inherit `text-base`, matching nav menu link size. -- **Status:** ✅ SUCCESS - -## Details - -Addressed inconsistent label sizing by removing explicit `text-xs` override and allowing components to inherit base text size from parent context. This ensures visual consistency across navigation UI. - diff --git a/.squad/orchestration-log/2026-03-29T18:08:58Z-aragorn.md b/.squad/orchestration-log/2026-03-29T18:08:58Z-aragorn.md deleted file mode 100644 index 1b35e0e..0000000 --- a/.squad/orchestration-log/2026-03-29T18:08:58Z-aragorn.md +++ /dev/null @@ -1,22 +0,0 @@ -# 2026-03-29T18:08:58Z — Aragorn (Sprint 1) - -## Outcome: COMPLETE ✓ - -### Work -- **Issue #88:** Diagnosed Auth0 role claim type — confirmed namespace requirement -- **Issue #89:** Configuration fix — set `Auth0:RoleClaimNamespace` in appsettings.Development.json -- **Tests:** Reviewed `tests/Web.Tests.Bunit/Auth/Auth0ClaimsTransformationTests.cs` to confirm test constant -- **Decision:** Documented role claim namespace requirement in `.squad/decisions/inbox/aragorn-role-claim-namespace.md` - -### Code Changes -- `src/Web/appsettings.Development.json`: Added Auth0 section with `RoleClaimNamespace = "https://issuetracker.com/roles"` -- Commented on issues #88 and #89 with diagnosis and fix - -### Build Status -- ✓ Build clean -- ✓ Tests passing - -### Notes -- Role claim namespace is critical for Auth0ClaimsTransformation Pass 1 to execute -- Empty namespace cascades to Pass 2 fallback (bare "roles"), but Auth0 uses namespaced claims -- IConfiguration.GetValue("Auth0:RoleClaimNamespace") is the access pattern diff --git a/.squad/orchestration-log/2026-03-29T18:08:58Z-legolas.md b/.squad/orchestration-log/2026-03-29T18:08:58Z-legolas.md deleted file mode 100644 index 5553347..0000000 --- a/.squad/orchestration-log/2026-03-29T18:08:58Z-legolas.md +++ /dev/null @@ -1,33 +0,0 @@ -# 2026-03-29T18:08:58Z — Legolas (Sprint 2+3) - -## Outcome: COMPLETE ✓ - -### Work -- **Issue #91:** Fixed Profile.razor GetAllRoleClaims to include Auth0 namespace claim type -- **Tests:** Added 2 NavMenu bUnit tests + created ProfileRolesTests.cs with 8 comprehensive tests -- **Configuration:** Injected IConfiguration into Profile.razor to read Auth0:RoleClaimNamespace -- **Decision:** Documented Profile.razor role claim fix in `.squad/decisions/inbox/legolas-profile-roles-fix.md` - -### Code Changes -- `src/Web/Components/User/Profile.razor`: - - GetAllRoleClaims() now accepts optional `roleClaimNamespace` parameter - - Includes Auth0 namespace claim type in role lookup - - Injects IConfiguration to read namespace from appsettings - - Belt-and-suspenders: shows roles from Auth0 namespace even if transformation misconfigured -- `tests/Web.Tests.Bunit/Auth/`: - - Added 2 NavMenu bUnit tests covering Admin link visibility -- `tests/Web.Tests.Bunit/Components/User/`: - - Created ProfileRolesTests.cs with 8 tests: - - Roles displayed when present - - No roles message when absent - - Namespace claim type handling - - Standard role claim handling - -### Build Status -- ✓ Build clean -- ✓ All 10 tests passing (2 NavMenu + 8 ProfileRoles) - -### Notes -- Profile component now resilient to transformation failures -- GetAllRoleClaims with namespace parameter supports both standard and Auth0 namespaced claims -- NavMenu tests ensure Admin links visibility is correct based on role claims diff --git a/.squad/orchestration-log/2026-03-29T18:08:58Z-sam.md b/.squad/orchestration-log/2026-03-29T18:08:58Z-sam.md deleted file mode 100644 index 08e07af..0000000 --- a/.squad/orchestration-log/2026-03-29T18:08:58Z-sam.md +++ /dev/null @@ -1,26 +0,0 @@ -# 2026-03-29T18:08:58Z — Sam (Sprint 2) - -## Outcome: COMPLETE ✓ - -### Work -- **Issue #90:** Added Pass 3 to Auth0ClaimsTransformation — auto-detect claim types ending in `/roles` -- **Tests:** Updated 2 tests in `Auth0ClaimsTransformationTests.cs` -- **Coverage:** Pass 3 now catches misconfigured namespaces and prevents silent failures -- **Decision:** Documented Pass 3 auto-detect logic in `.squad/decisions/inbox/sam-pass3-auto-detect.md` - -### Code Changes -- `src/Web/Auth/Auth0ClaimsTransformation.cs`: - - Added Pass 3 to `TransformAsync()`: scans all claims for types ending in `/roles` when Passes 1 & 2 find nothing - - Belt-and-suspenders safety net for misconfigured namespace -- `tests/Web.Tests.Bunit/Auth/Auth0ClaimsTransformationTests.cs`: - - Added 2 test cases covering Pass 3 auto-detect scenario - - Verified role claim is added to `ClaimTypes.Role` even when namespace is misconfigured - -### Build Status -- ✓ Build clean -- ✓ All Auth0 transformation tests passing - -### Notes -- Pass 3 prevents Admin role hidden in NavMenu when namespace config is missing -- Auto-detect scans all claims ending with `/roles` (case-insensitive) -- Handles both "https://example.com/roles" and custom namespace patterns diff --git a/.squad/orchestration-log/2026-03-29T18:47:42Z-gimli-adminlayout.md b/.squad/orchestration-log/2026-03-29T18:47:42Z-gimli-adminlayout.md deleted file mode 100644 index a14b17b..0000000 --- a/.squad/orchestration-log/2026-03-29T18:47:42Z-gimli-adminlayout.md +++ /dev/null @@ -1,34 +0,0 @@ -# Orchestration Log — Gimli Sprint 2 - -**Agent:** Gimli (Test Architecture Engineer) -**Timestamp:** 2026-03-29T18:47:42Z -**Task:** Create AdminPageLayout regression tests -**Branch:** squad/90-auth0-claims-pass3-auto-detect - -## Work Completed - -- **File Created:** `tests/Web.Tests.Bunit/Components/Pages/Admin/AdminPageLayoutTests.cs` -- **Test Count:** 14 bUnit tests -- **Test Categories:** - - Component rendering (title, description, child content) - - Navigation link behavior and CSS classes - - Dark mode styling - - Reflection guards: enforce AdminPageLayout **never** inherits `LayoutComponentBase` - - CSS class assertions for Tailwind styling - -- **Key Test:** Reflection guard validates that AdminPageLayout does NOT inherit `LayoutComponentBase`, preventing future bugs where developers accidentally misuse the component as a layout. - -## Build Status -✅ Build clean - -## Test Status -✅ All 14 tests passing - -## Architecture Significance -- Enforces component usage contract: wrapper only, never layout directive -- Prevents regression where AdminPageLayout might be accidentally used with `@layout` directive -- Contributes to overall architecture validation suite - -## Next Steps -- PR review -- Monitor for similar patterns in other wrapper components diff --git a/.squad/orchestration-log/2026-03-29T18:47:42Z-legolas-adminlayout.md b/.squad/orchestration-log/2026-03-29T18:47:42Z-legolas-adminlayout.md deleted file mode 100644 index a4c990d..0000000 --- a/.squad/orchestration-log/2026-03-29T18:47:42Z-legolas-adminlayout.md +++ /dev/null @@ -1,29 +0,0 @@ -# Orchestration Log — Legolas Sprint 2 - -**Agent:** Legolas (UI/Component Engineer) -**Timestamp:** 2026-03-29T18:47:42Z -**Task:** Add warning comment to AdminPageLayout.razor -**Branch:** squad/90-auth0-claims-pass3-auto-detect - -## Work Completed - -- **File Modified:** `src/Web/Components/Pages/Admin/AdminPageLayout.razor` -- **Change:** Added leading comment block warning developers: - ``` - @* ⚠️ COMPONENT WRAPPER — NOT A LAYOUT - Use: ... - Do NOT: @layout AdminPageLayout (this component does NOT inherit LayoutComponentBase) - *@ - ``` -- **Rationale:** AdminPageLayout is a wrapper component, not a Blazor layout. Must be used as `` with parameters, not via `@layout` directive. -- **Impact:** Prevents future misuse and clarifies component intent to other developers. - -## Build Status -✅ Build clean - -## Test Status -✅ All existing tests passing (14 AdminPageLayout bUnit tests by Gimli) - -## Next Steps -- PR review and merge to main -- Consider adding similar guards to other wrapper components diff --git a/.squad/orchestration-log/2026-03-29T21-49-00Z-aragorn.md b/.squad/orchestration-log/2026-03-29T21-49-00Z-aragorn.md deleted file mode 100644 index a79077d..0000000 --- a/.squad/orchestration-log/2026-03-29T21-49-00Z-aragorn.md +++ /dev/null @@ -1,17 +0,0 @@ -# Aragorn Orchestration — PR Review Process - -**Date:** 2026-03-29T21:49:00Z -**Task:** Implement formal PR review process - -## Deliverables -- ✅ Created `.github/pull_request_template.md` with domain checklist -- ✅ Updated `.squad/ceremonies.md`: 3 new ceremonies (PR Review Gate, CHANGES_REQUESTED, Conflict Resolution) -- ✅ Updated `.squad/routing.md`: 4 new PR state signals -- ✅ Updated `.squad/agents/ralph/charter.md`: Pre-review + pre-merge gate tables -- ✅ Created `.squad/decisions/inbox/aragorn-pr-review-process.md` - -## Outcomes -- PR template drives required reviewers via domain checkboxes -- Review ceremonies define CHANGES_REQUESTED rejection protocol with author lockout -- Ralph gates enforce CI green + MERGEABLE pre-review, APPROVED + CI green pre-merge -- Decision documented for team reference diff --git a/.squad/orchestration-log/2026-03-29T21-49-00Z-boromir.md b/.squad/orchestration-log/2026-03-29T21-49-00Z-boromir.md deleted file mode 100644 index 0acde02..0000000 --- a/.squad/orchestration-log/2026-03-29T21-49-00Z-boromir.md +++ /dev/null @@ -1,17 +0,0 @@ -# Boromir Orchestration — GitHub Infrastructure - -**Date:** 2026-03-29T21:49:00Z -**Task:** Enable GitHub branch protection and CI/CD infrastructure - -## Deliverables -- ✅ Fixed `.github/workflows/squad-ci.yml` (replaced stub with real `dotnet build --configuration Release`) -- ✅ Created `.github/CODEOWNERS` for auto-review routing by file path -- ✅ Enabled branch protection on `main`: 1 required approval, dismiss stale reviews, build check required -- ✅ Enforced squash-only merges + auto-delete branches on merge -- ✅ Created `.squad/decisions/inbox/boromir-github-protection.md` - -## Outcomes -- CI pipeline now validates all PR builds before merge -- CODEOWNERS auto-requests @mpaulosky based on changed files -- Main branch protected with strict merge requirements -- Decision documented for reference and audit trail diff --git a/.squad/orchestration-log/2026-03-29T21:33:13Z-ralph.md b/.squad/orchestration-log/2026-03-29T21:33:13Z-ralph.md deleted file mode 100644 index 0f25557..0000000 --- a/.squad/orchestration-log/2026-03-29T21:33:13Z-ralph.md +++ /dev/null @@ -1,11 +0,0 @@ -# Ralph Work-Check Cycle — 2026-03-29T21:33:13Z - -**Agent:** Ralph (Work Monitor) - -**Cycle:** 1 - -**Output:** PR #102 ("style: UI polish — nav, footer, SignalR, dashboard cleanup") — all CI checks ✅ green. Merged via squash merge. - -**Board State:** 0 open issues, 0 open PRs. - -**Status:** ✅ Complete diff --git a/.squad/orchestration-log/2026-04-01T17:15:15Z-ralph.md b/.squad/orchestration-log/2026-04-01T17:15:15Z-ralph.md deleted file mode 100644 index 8dd32a9..0000000 --- a/.squad/orchestration-log/2026-04-01T17:15:15Z-ralph.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration: Ralph - -## Agent Details -- **Name:** Ralph -- **Role:** Work Monitor -- **Mode:** Direct scan + push - -## Why Chosen -Ralph activated as work monitor by mpaulosky to scan the squad board and diagnose CI failures. - -## Work Executed -- **Task:** Board scan for CI issues -- **Issue Found:** PR #160 — Architecture.Tests layer boundary failure -- **Root Cause Diagnosis:** `AuditLogRepository` missing `IRepository` implementation -- **Files Involved:** `src/Domain/Features/Auditing/AuditLogRepository.cs` -- **Fix Source:** Local commit `ad6a79f` (pre-existing, not pushed) -- **Action:** Pushed commit to `origin/squad/133-mediatr-admin-handlers` - -## Test Results -- Pre-push validation: All 40 tests passed - -## Outcome -✅ CI fix deployed -✅ Team visibility improved (fix now in remote) -→ Legolas spawned for issue #136 - -## Spawn -Legolas triggered for issue #136 (/admin/users page scaffold) on branch `squad/136-admin-users-page-scaffold` diff --git a/.squad/orchestration-log/2026-04-01T19:49:17Z-bilbo.md b/.squad/orchestration-log/2026-04-01T19:49:17Z-bilbo.md deleted file mode 100644 index cc67c2b..0000000 --- a/.squad/orchestration-log/2026-04-01T19:49:17Z-bilbo.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration Log — Bilbo (Tech Blogger) -**Timestamp:** 2026-04-01T19:49:17Z -**Agent:** Bilbo (Tech Blogger) -**Mode:** background -**Status:** ✅ SUCCESS - ---- - -## Task -Catch up on 2 missing mandatory release blog posts (v0.3.0, v0.4.0) - ---- - -## Files Produced -- `docs/blog/2026-04-01-release-v0-3-0.md` — Release blog post for v0.3.0 -- `docs/blog/2026-04-01-release-v0-4-0.md` — Release blog post for v0.4.0 -- `docs/blog/index.md` — Updated blog index -- `docs/index.html` — Updated BLOG table - ---- - -## Outcome -✅ SUCCESS — Committed as **246099c** - ---- - -## Summary -Bilbo successfully authored and published two missing release blog posts covering v0.3.0 and v0.4.0 releases. Blog index and main docs index were updated to reflect new posts. diff --git a/.squad/orchestration-log/2026-04-01T19:49:17Z-frodo.md b/.squad/orchestration-log/2026-04-01T19:49:17Z-frodo.md deleted file mode 100644 index 8eef7a4..0000000 --- a/.squad/orchestration-log/2026-04-01T19:49:17Z-frodo.md +++ /dev/null @@ -1,25 +0,0 @@ -# Orchestration Log — Frodo (Tech Writer) -**Timestamp:** 2026-04-01T19:49:17Z -**Agent:** Frodo (Tech Writer) -**Mode:** background -**Status:** ✅ SUCCESS - ---- - -## Task -Add Release Notes section to docs/index.html - ---- - -## Files Produced -- `docs/index.html` — Release Notes section added before Dev Blog section with RELEASES_START/RELEASES_END markers; footer updated - ---- - -## Outcome -✅ SUCCESS — Committed as **5a6f38b** - ---- - -## Summary -Frodo successfully structured and added a Release Notes section to the main documentation page with proper markers and footer update. Section placement ensures release information is prominently visible before the Dev Blog section. diff --git a/.squad/orchestration-log/2026-04-02-process-review.md b/.squad/orchestration-log/2026-04-02-process-review.md deleted file mode 100644 index 3258669..0000000 --- a/.squad/orchestration-log/2026-04-02-process-review.md +++ /dev/null @@ -1,25 +0,0 @@ -# Orchestration Log — Process & Docs Review Session -**Date:** 2026-04-02 -**Orchestrator:** Ralph (Project Manager) - -## Agents Spawned - -| Agent | Task | Branch | PR | Status | -|-------|------|--------|----|--------| -| Scribe | Memory sweep — decisions archive + history summarization | squad/scribe-memory-sweep | #186 | ✅ Merged | -| Aragorn | Process review — ceremonies, routing, skills | squad/process-review-2026-04-02 | #183 | ✅ Merged | -| Frodo | Docs audit — README, CONTRIBUTING, XML docs | squad/frodo-docs-audit-2026-04-02 | #185 | ✅ Merged | -| Gandalf | Security review — Auth0 Management, routing signals, history cleanup | squad/gandalf-security-review-2026-04-02 | #184 | ✅ Merged | - -## Changes Merged to Main - -- decisions.md: trimmed 118 pre-2026-02 lines, decisions-archive.md created with 3 entries -- ceremonies.md: Sprint Review + Issue Grooming ceremonies added, Gandalf reviewer row expanded -- routing.md: 8 new routing signals (Admin/Labels/Security domains) -- 3 new skills: auth0-management-api, labels-feature-patterns, auth0-management-security -- Agent histories: Gimli, Legolas, Sam, Gandalf summarized (88% reduction) - -## Outstanding - -- [MEDIUM] Gandalf finding: No audit log for role assign/revoke in UserManagementService — filed in decisions inbox for tracking as follow-up issue -- identity/now.md, identity/wisdom.md — updated in this Scribe pass diff --git a/Directory.Packages.props b/Directory.Packages.props index be10774..ad7cb66 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -4,21 +4,21 @@ - - - + + + - - - - - + + + + + - + - - + + @@ -27,43 +27,43 @@ - - + + - - - - - - - - + + + + + + + + - + - + - + - - + + - + - - - - - - - + + + + + + + - \ No newline at end of file + diff --git a/global.json b/global.json index 01f9338..bab7a3e 100644 --- a/global.json +++ b/global.json @@ -1,6 +1,6 @@ { "sdk": { - "version": "10.0.100-preview.4.25258.110", + "version": "10.0.202", "rollForward": "latestMinor", "allowPrerelease": false } diff --git a/src/AppHost/AppHost.cs b/src/AppHost/AppHost.cs index 90bb53e..3d5d5ec 100644 --- a/src/AppHost/AppHost.cs +++ b/src/AppHost/AppHost.cs @@ -15,13 +15,20 @@ var auth0MgmtClientId = builder.AddParameter("auth0MgmtClientId", secret: true); var auth0MgmtClientSecret = builder.AddParameter("auth0MgmtClientSecret", secret: true); +var isTesting = string.Equals(builder.Environment.EnvironmentName, "Testing", StringComparison.OrdinalIgnoreCase) + || string.Equals(Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT"), "Testing", StringComparison.OrdinalIgnoreCase); + // Add Web project with service discovery and health checks -builder.AddProject("web") +var web = builder.AddProject("web") .WithReference(mongodb) .WithReference(redis) .WaitFor(redis) - .WithHttpHealthCheck("/health") .WithEnvironment("Auth0Management__ClientId", auth0MgmtClientId) .WithEnvironment("Auth0Management__ClientSecret", auth0MgmtClientSecret); +if (!isTesting) +{ + web.WithHttpHealthCheck("/health"); +} + builder.Build().Run(); diff --git a/src/Web/Features/Admin/Users/UserManagementExtensions.cs b/src/Web/Features/Admin/Users/UserManagementExtensions.cs index 7dc2f2d..d2c41ed 100644 --- a/src/Web/Features/Admin/Users/UserManagementExtensions.cs +++ b/src/Web/Features/Admin/Users/UserManagementExtensions.cs @@ -7,8 +7,12 @@ // Project Name : Web // ============================================= +using Auth0.ManagementApi; + using Domain.Features.Admin.Abstractions; +using Microsoft.Extensions.Options; + namespace Web.Features.Admin.Users; /// @@ -33,6 +37,24 @@ public static IServiceCollection AddUserManagement( services.Configure( configuration.GetSection(Auth0ManagementOptions.SectionName)); + // Register the Auth0 management client as a singleton; the SDK's + // ClientCredentialsTokenProvider handles M2M token acquisition and caching internally. + services.AddSingleton(sp => + { + var opts = sp.GetRequiredService>().Value; + var audience = string.IsNullOrWhiteSpace(opts.Audience) ? null : opts.Audience; + + return new ManagementClient(new ManagementClientOptions + { + Domain = opts.Domain, + TokenProvider = new ClientCredentialsTokenProvider( + opts.Domain, + opts.ClientId, + opts.ClientSecret, + audience: audience) + }); + }); + // Register the service as scoped — a new instance per HTTP request. services.AddScoped(); diff --git a/src/Web/Features/Admin/Users/UserManagementService.cs b/src/Web/Features/Admin/Users/UserManagementService.cs index fa5cdf6..21b6c64 100644 --- a/src/Web/Features/Admin/Users/UserManagementService.cs +++ b/src/Web/Features/Admin/Users/UserManagementService.cs @@ -8,13 +8,10 @@ // ============================================= using System.Buffers.Binary; -using System.Net.Http.Json; using System.Text.Json; -using System.Text.Json.Serialization; using Auth0.ManagementApi; -using Auth0.ManagementApi.Models; -using Auth0.ManagementApi.Paging; +using Auth0.ManagementApi.Users; using Domain.Abstractions; using Domain.Features.Admin.Abstractions; @@ -22,27 +19,24 @@ using Microsoft.Extensions.Caching.Distributed; using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Options; namespace Web.Features.Admin.Users; /// -/// Implements using the Auth0 Management API v2. +/// Implements using the Auth0 Management API v8. /// /// -/// An M2M access token is obtained via the OAuth 2.0 client credentials flow and cached in -/// with a 24 h TTL minus a 5-minute safety margin. Role IDs are -/// resolved dynamically by name and cached for 30 minutes so they are never hardcoded. +/// Credentials are managed by the injected , which uses +/// ClientCredentialsTokenProvider to handle M2M token acquisition and caching internally. +/// Role IDs are resolved dynamically by name and cached for 30 minutes so they are never hardcoded. /// /// Rate limits: Auth0 Management API returns HTTP 429 on burst. Add a Polly retry -/// policy (per ADR #130) in a follow-up task once the HttpClientManagementConnection -/// integration is confirmed against the tenant's SDK version. +/// policy (per ADR #130) in a follow-up task. /// /// public sealed class UserManagementService : IUserManagementService { - // ── IMemoryCache keys (token + role-ID map — DO NOT CHANGE) ────────────── - private const string TokenCacheKey = "Auth0Management:Token"; + // ── IMemoryCache key (role-ID map) ──────────────────────────────────────── private const string RolesCacheKey = "Auth0Management:Roles"; // ── IDistributedCache keys (result data — Sprint 2) ────────────────────── @@ -58,8 +52,7 @@ public sealed class UserManagementService : IUserManagementService private readonly IMemoryCache _cache; private readonly IDistributedCache _distributedCache; - private readonly IHttpClientFactory _httpClientFactory; - private readonly Auth0ManagementOptions _options; + private readonly IManagementApiClient _managementClient; private readonly ILogger _logger; /// @@ -68,14 +61,12 @@ public sealed class UserManagementService : IUserManagementService public UserManagementService( IMemoryCache cache, IDistributedCache distributedCache, - IHttpClientFactory httpClientFactory, - IOptions options, + IManagementApiClient managementClient, ILogger logger) { _cache = cache; _distributedCache = distributedCache; - _httpClientFactory = httpClientFactory; - _options = options.Value; + _managementClient = managementClient; _logger = logger; } @@ -101,25 +92,35 @@ public async Task>> ListUsersAsync( return Result.Ok>(cached); } - using var client = await GetManagementClientAsync(ct).ConfigureAwait(false); + // Auth0 uses 0-based page numbering; callers pass 1-based pages. var auth0Page = Math.Max(0, page - 1); - var users = await client.Users - .GetAllAsync(new GetUsersRequest(), new PaginationInfo(auth0Page, perPage, false), ct) + var pager = await _managementClient.Users + .ListAsync(new ListUsersRequestParameters { Page = auth0Page, PerPage = perPage }, null, ct) .ConfigureAwait(false); + var users = pager.CurrentPage.Items; + // Auth0's list endpoint does not include role assignments; fetch them per user in // parallel to avoid sequential N+1 latency. var summaries = await Task.WhenAll(users.Select(async u => { - var roles = await client.Users - .GetRolesAsync(u.UserId, new PaginationInfo(0, 100, false), ct) + if (string.IsNullOrWhiteSpace(u.UserId)) + { + _logger.LogWarning( + "Skipping Auth0 role lookup for listed user with missing UserId. Email={Email}", + u.Email ?? string.Empty); + return MapUser(u) with { UserId = string.Empty }; + } + + var rolesPager = await _managementClient.Users.Roles + .ListAsync(u.UserId, new ListUserRolesRequestParameters { PerPage = 100 }, null, ct) .ConfigureAwait(false); return MapUser(u) with { - Roles = roles.Select(r => r.Name ?? string.Empty).ToList() + Roles = rolesPager.CurrentPage.Items.Select(r => r.Name ?? string.Empty).ToList() }; })).ConfigureAwait(false); @@ -167,20 +168,19 @@ public async Task> GetUserByIdAsync( return Result.Ok(cached); } - using var client = await GetManagementClientAsync(ct).ConfigureAwait(false); - var user = await client.Users - .GetAsync(userId, cancellationToken: ct) + var user = await _managementClient.Users + .GetAsync(userId, new GetUserRequestParameters(), null, ct) .ConfigureAwait(false); // Fetch the roles assigned to this user (requires a separate API call). - var rolesList = await client.Users - .GetRolesAsync(userId, new PaginationInfo(0, 100, false), ct) + var rolesPager = await _managementClient.Users.Roles + .ListAsync(userId, new ListUserRolesRequestParameters { PerPage = 100 }, null, ct) .ConfigureAwait(false); var summary = MapUser(user) with { - Roles = rolesList.Select(r => r.Name ?? string.Empty).ToList() + Roles = rolesPager.CurrentPage.Items.Select(r => r.Name ?? string.Empty).ToList() }; await SetInDistributedCacheAsync(cacheKey, summary, UserByIdTtl, ct).ConfigureAwait(false); @@ -216,8 +216,7 @@ public async Task> AssignRolesAsync( try { - using var client = await GetManagementClientAsync(ct).ConfigureAwait(false); - var roleMap = await GetRoleMapAsync(client, ct).ConfigureAwait(false); + var roleMap = await GetRoleMapAsync(ct).ConfigureAwait(false); var unknown = roleNamesList.Where(r => !roleMap.ContainsKey(r)).ToList(); if (unknown.Count > 0) @@ -229,8 +228,8 @@ public async Task> AssignRolesAsync( var roleIds = roleNamesList.Select(r => roleMap[r]).ToArray(); - await client.Users - .AssignRolesAsync(userId, new AssignRolesRequest { Roles = roleIds }, ct) + await _managementClient.Users.Roles + .AssignAsync(userId, new AssignUserRolesRequestContent { Roles = roleIds }, null, ct) .ConfigureAwait(false); } catch (Exception ex) when (ex is not OperationCanceledException) @@ -286,8 +285,7 @@ public async Task> RemoveRolesAsync( try { - using var client = await GetManagementClientAsync(ct).ConfigureAwait(false); - var roleMap = await GetRoleMapAsync(client, ct).ConfigureAwait(false); + var roleMap = await GetRoleMapAsync(ct).ConfigureAwait(false); var unknown = roleNamesList.Where(r => !roleMap.ContainsKey(r)).ToList(); if (unknown.Count > 0) @@ -299,8 +297,8 @@ public async Task> RemoveRolesAsync( var roleIds = roleNamesList.Select(r => roleMap[r]).ToArray(); - await client.Users - .RemoveRolesAsync(userId, new AssignRolesRequest { Roles = roleIds }, ct) + await _managementClient.Users.Roles + .DeleteAsync(userId, new DeleteUserRolesRequestContent { Roles = roleIds }, null, ct) .ConfigureAwait(false); } catch (Exception ex) when (ex is not OperationCanceledException) @@ -350,13 +348,12 @@ public async Task>> ListRolesAsync(Cancella return Result.Ok>(cached); } - using var client = await GetManagementClientAsync(ct).ConfigureAwait(false); - var roles = await client.Roles - .GetAllAsync(new GetRolesRequest(), new PaginationInfo(0, 100, false), ct) + var pager = await _managementClient.Roles + .ListAsync(new ListRolesRequestParameters { PerPage = 100 }, null, ct) .ConfigureAwait(false); - var result = roles + var result = pager.CurrentPage.Items .Select(r => new RoleAssignment { RoleId = r.Id ?? string.Empty, @@ -480,83 +477,21 @@ await _distributedCache.SetAsync( } /// - /// Creates a using a cached M2M access token. - /// - private async Task GetManagementClientAsync(CancellationToken ct) - { - var token = await GetOrFetchTokenAsync(ct).ConfigureAwait(false); - return new ManagementApiClient(token, new Uri($"https://{_options.Domain}/api/v2/")); - } - - /// - /// Returns a cached M2M access token, fetching a fresh one from Auth0 when expired. - /// Uses to avoid concurrent cold-start - /// races where multiple in-flight requests each fetch a new token simultaneously. - /// - private async Task GetOrFetchTokenAsync(CancellationToken ct) - { - var token = await _cache.GetOrCreateAsync(TokenCacheKey, async entry => - { - _logger.LogDebug( - "Fetching fresh Auth0 Management API token for domain '{Domain}'.", - _options.Domain); - - using var httpClient = _httpClientFactory.CreateClient(); - - using var requestBody = new FormUrlEncodedContent( - [ - new KeyValuePair("grant_type", "client_credentials"), - new KeyValuePair("client_id", _options.ClientId), - new KeyValuePair("client_secret", _options.ClientSecret), - new KeyValuePair("audience", _options.Audience) - ]); - - using var response = await httpClient - .PostAsync($"https://{_options.Domain}/oauth/token", requestBody, ct) - .ConfigureAwait(false); - - response.EnsureSuccessStatusCode(); - - var tokenResponse = await response.Content - .ReadFromJsonAsync(cancellationToken: ct) - .ConfigureAwait(false) - ?? throw new InvalidOperationException( - "Auth0 token endpoint returned an empty response."); - - // Cache with a 5-minute safety margin so we always have time to act on the token. - var ttl = tokenResponse.ExpiresIn > 300 - ? tokenResponse.ExpiresIn - 300 - : tokenResponse.ExpiresIn; - - entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(ttl); - - _logger.LogDebug("Auth0 Management API token cached. TTL={Ttl}s.", ttl); - - return tokenResponse.AccessToken; - }).ConfigureAwait(false); - - return token ?? throw new InvalidOperationException( - "Auth0 token cache returned null — token fetch may have failed."); - } - - /// - /// Returns a name → ID map of all tenant roles, backed by a 30-minute cache. + /// Returns a name → ID map of all tenant roles, backed by a 30-minute in-memory cache. /// Uses to avoid race conditions /// on concurrent cold starts. /// - private async Task> GetRoleMapAsync( - ManagementApiClient client, - CancellationToken ct) + private async Task> GetRoleMapAsync(CancellationToken ct) { var map = await _cache.GetOrCreateAsync(RolesCacheKey, async entry => { - var roles = await client.Roles - .GetAllAsync(new GetRolesRequest(), new PaginationInfo(0, 100, false), ct) + var pager = await _managementClient.Roles + .ListAsync(new ListRolesRequestParameters { PerPage = 100 }, null, ct) .ConfigureAwait(false); entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30); - return roles + return pager.CurrentPage.Items .Where(r => r.Name is not null && r.Id is not null) .ToDictionary(r => r.Name!, r => r.Id!, StringComparer.OrdinalIgnoreCase); }).ConfigureAwait(false); @@ -564,23 +499,38 @@ private async Task> GetRoleMapAsync( return map ?? []; } - /// Maps an Auth0 to . - private static AdminUserSummary MapUser(User user) => new() + /// Maps an Auth0 (list result) to . + private static AdminUserSummary MapUser(UserResponseSchema user) => new() + { + UserId = user.UserId ?? string.Empty, + Email = user.Email ?? string.Empty, + Name = user.Name ?? user.Email ?? string.Empty, + Picture = user.Picture ?? string.Empty, + Roles = [], + LastLogin = ParseLastLogin(user.LastLogin), + IsBlocked = user.Blocked ?? false + }; + + /// Maps an Auth0 (single-user result) to . + private static AdminUserSummary MapUser(GetUserResponseContent user) => new() { UserId = user.UserId ?? string.Empty, Email = user.Email ?? string.Empty, - Name = user.FullName ?? user.Email ?? string.Empty, + Name = user.Name ?? user.Email ?? string.Empty, Picture = user.Picture ?? string.Empty, Roles = [], - LastLogin = user.LastLogin is { } lastLogin - ? new DateTimeOffset(DateTime.SpecifyKind(lastLogin, DateTimeKind.Utc)) - : null, + LastLogin = ParseLastLogin(user.LastLogin), IsBlocked = user.Blocked ?? false }; - /// Thin DTO for deserializing the Auth0 token endpoint response. - private sealed record TokenResponse( - [property: JsonPropertyName("access_token")] string AccessToken, - [property: JsonPropertyName("token_type")] string TokenType, - [property: JsonPropertyName("expires_in")] int ExpiresIn); + /// + /// Safely converts a last-login field to a nullable + /// , returning if the value is absent + /// or unparseable. + /// + private static DateTimeOffset? ParseLastLogin(UserDateSchema? lastLogin) + { + if (lastLogin is null) return null; + return lastLogin.TryGetString(out var s) && DateTimeOffset.TryParse(s, out var dto) ? dto : null; + } } diff --git a/tests/Web.Tests.Integration/CustomWebApplicationFactory.cs b/tests/Web.Tests.Integration/CustomWebApplicationFactory.cs index a931bd9..1579f6a 100644 --- a/tests/Web.Tests.Integration/CustomWebApplicationFactory.cs +++ b/tests/Web.Tests.Integration/CustomWebApplicationFactory.cs @@ -20,6 +20,10 @@ using MongoDB.Driver; +using Domain.Abstractions; +using Domain.Features.Admin.Abstractions; +using Domain.Features.Admin.Models; + using Persistence.MongoDb; using Persistence.MongoDb.Configurations; @@ -115,7 +119,13 @@ protected override void ConfigureWebHost(IWebHostBuilder builder) // Auth0 settings (not used since we mock auth, but required for startup) ["Auth0:Domain"] = "test.auth0.com", ["Auth0:ClientId"] = "test-client-id", - ["Auth0:ClientSecret"] = "test-client-secret" + ["Auth0:ClientSecret"] = "test-client-secret", + // Auth0 Management settings are required because the v8 client validates + // these options at service-construction time before any outbound call occurs. + ["Auth0Management:Domain"] = "test.auth0.com", + ["Auth0Management:ClientId"] = "test-client-id", + ["Auth0Management:ClientSecret"] = "test-client-secret", + ["Auth0Management:Audience"] = "https://test.auth0.com/api/v2/" }; configBuilder.AddInMemoryCollection(testConfig); @@ -153,6 +163,23 @@ protected override void ConfigureWebHost(IWebHostBuilder builder) ConnectionString = connectionString, DatabaseName = databaseName })); + + services.RemoveAll(); + services.AddScoped(_ => + { + var substitute = Substitute.For(); + substitute.ListUsersAsync(Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(Task.FromResult(Result.Ok>([]))); + substitute.GetUserByIdAsync(Arg.Any(), Arg.Any()) + .Returns(Task.FromResult(Result.Ok(AdminUserSummary.Empty))); + substitute.ListRolesAsync(Arg.Any()) + .Returns(Task.FromResult(Result.Ok>([]))); + substitute.AssignRolesAsync(Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(Task.FromResult(Result.Ok(true))); + substitute.RemoveRolesAsync(Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(Task.FromResult(Result.Ok(true))); + return substitute; + }); }); } diff --git a/tests/Web.Tests/Features/Admin/Users/UserManagementServiceCacheTests.cs b/tests/Web.Tests/Features/Admin/Users/UserManagementServiceCacheTests.cs index 25218dc..11bc8d4 100644 --- a/tests/Web.Tests/Features/Admin/Users/UserManagementServiceCacheTests.cs +++ b/tests/Web.Tests/Features/Admin/Users/UserManagementServiceCacheTests.cs @@ -7,15 +7,17 @@ // Project Name : Web // ============================================= -using System.Text; using System.Text.Json; +using Auth0.ManagementApi; + using Domain.Abstractions; using Domain.Features.Admin.Models; +using Microsoft.Extensions.Options; + using Microsoft.Extensions.Caching.Distributed; using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Options; using Web.Features.Admin.Users; @@ -26,10 +28,9 @@ namespace Web.Tests.Features.Admin.Users; /// /// These tests use a real so cache read/write round-trips /// are exercised without mocking serialization internals. The Auth0 Management API layer is -/// replaced by a that returns precanned JSON for the -/// M2M token endpoint. Management API calls that would contact Auth0 are expected to fail with -/// — the tests assert cache behaviour, not the -/// success path of the Management API itself. +/// replaced by an NSubstitute stub. Cache-miss tests assert +/// (NSubstitute default returns a null-valued struct +/// which causes NullReferenceException, caught as ExternalService by the service). /// public sealed class UserManagementServiceCacheTests { @@ -37,67 +38,27 @@ public sealed class UserManagementServiceCacheTests // Infrastructure // ────────────────────────────────────────────────────────────────────────── - private static Auth0ManagementOptions DefaultOptions => new() - { - ClientId = "test-client-id", - ClientSecret = "test-client-secret", - Domain = "test-tenant.auth0.com", - Audience = "https://test-tenant.auth0.com/api/v2/" - }; - /// /// Creates a backed by a real in-memory distributed /// cache so serialization/deserialization round-trips are tested. /// private static (UserManagementService Sut, IDistributedCache DistributedCache) CreateSut( - IHttpClientFactory? httpClientFactory = null) + IManagementApiClient? managementApiClient = null) { var memoryCache = new MemoryCache(new MemoryCacheOptions()); var distributedCache = new MemoryDistributedCache(Options.Create(new MemoryDistributedCacheOptions())); - var factory = httpClientFactory ?? Substitute.For(); + var client = managementApiClient ?? Substitute.For(); var logger = Substitute.For>(); var sut = new UserManagementService( memoryCache, distributedCache, - factory, - Options.Create(DefaultOptions), + client, logger); return (sut, distributedCache); } - /// - /// Builds a stub whose CreateClient always returns - /// an wired to a handler that responds to the Auth0 token endpoint - /// with a valid access-token JSON payload. All other URLs return 404. - /// - private static IHttpClientFactory TokenOnlyHttpClientFactory() - { - var handler = new FakeHttpMessageHandler(request => - { - if (request.RequestUri?.AbsolutePath.EndsWith("/oauth/token") == true) - { - var json = JsonSerializer.Serialize(new - { - access_token = "fake-management-token", - token_type = "Bearer", - expires_in = 86400 - }); - return new HttpResponseMessage(HttpStatusCode.OK) - { - Content = new StringContent(json, Encoding.UTF8, "application/json") - }; - } - - return new HttpResponseMessage(HttpStatusCode.NotFound); - }); - - var factory = Substitute.For(); - factory.CreateClient(Arg.Any()).Returns(new HttpClient(handler)); - return factory; - } - /// /// Directly writes a serialized value into the distributed cache so cache-hit tests /// do not depend on a prior Auth0 call. @@ -125,8 +86,8 @@ public async Task ListUsersAsync_SecondCall_HitsCacheAndSkipsAuth0() { // Arrange — pre-populate the distributed cache with a serialised user list using // version=0 (the default when no version entry exists). - var httpClientFactory = Substitute.For(); - var (sut, distributedCache) = CreateSut(httpClientFactory: httpClientFactory); + var managementClient = Substitute.For(); + var (sut, distributedCache) = CreateSut(managementApiClient: managementClient); var expectedUsers = new List { new() { UserId = "auth0|u1", Email = "a@test.com", Name = "Alpha", Roles = ["Admin"] }, @@ -144,19 +105,19 @@ public async Task ListUsersAsync_SecondCall_HitsCacheAndSkipsAuth0() result.Success.Should().BeTrue(); result.Value.Should().HaveCount(2); result.Value![0].UserId.Should().Be("auth0|u1"); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } [Fact] public async Task ListUsersAsync_CacheMiss_AttemptsAuth0Call() { - // Arrange — empty cache; factory is called once for the token fetch. - var (sut, _) = CreateSut(TokenOnlyHttpClientFactory()); + // Arrange — empty cache; NSubstitute default on IManagementApiClient → ExternalService + var (sut, _) = CreateSut(); - // Act — Auth0 Management API will 404 after token exchange → ExternalService error + // Act — Management API stub returns default (null-valued struct) → ExternalService var result = await sut.ListUsersAsync(1, 10, CancellationToken.None); - // Assert — the call reached Auth0 (got ExternalService, not Validation) + // Assert — the call reached Auth0 path (got ExternalService, not Validation) result.Failure.Should().BeTrue(); result.ErrorCode.Should().Be(ResultErrorCode.ExternalService); } @@ -169,8 +130,8 @@ public async Task ListUsersAsync_CacheMiss_AttemptsAuth0Call() public async Task GetUserByIdAsync_SecondCall_HitsCacheAndSkipsAuth0() { // Arrange - var httpClientFactory = Substitute.For(); - var (sut, distributedCache) = CreateSut(httpClientFactory: httpClientFactory); + var managementClient = Substitute.For(); + var (sut, distributedCache) = CreateSut(managementApiClient: managementClient); var userId = "auth0|user123"; var expected = new AdminUserSummary { @@ -189,14 +150,14 @@ public async Task GetUserByIdAsync_SecondCall_HitsCacheAndSkipsAuth0() result.Success.Should().BeTrue(); result.Value!.UserId.Should().Be(userId); result.Value.Roles.Should().BeEquivalentTo(["Admin", "User"]); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } [Fact] public async Task GetUserByIdAsync_CacheMiss_AttemptsAuth0Call() { - // Arrange — empty cache → falls through to Auth0 - var (sut, _) = CreateSut(TokenOnlyHttpClientFactory()); + // Arrange — empty cache → falls through to Auth0 stub → ExternalService + var (sut, _) = CreateSut(); // Act var result = await sut.GetUserByIdAsync("auth0|nonexistent", CancellationToken.None); @@ -214,8 +175,8 @@ public async Task GetUserByIdAsync_CacheMiss_AttemptsAuth0Call() public async Task ListRolesAsync_SecondCall_HitsCacheAndSkipsAuth0() { // Arrange - var httpClientFactory = Substitute.For(); - var (sut, distributedCache) = CreateSut(httpClientFactory: httpClientFactory); + var managementClient = Substitute.For(); + var (sut, distributedCache) = CreateSut(managementApiClient: managementClient); var expectedRoles = new List { new() { RoleId = "rol_1", RoleName = "Admin", Description = "Administrator" }, @@ -231,14 +192,14 @@ public async Task ListRolesAsync_SecondCall_HitsCacheAndSkipsAuth0() result.Success.Should().BeTrue(); result.Value.Should().HaveCount(2); result.Value![0].RoleName.Should().Be("Admin"); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } [Fact] public async Task ListRolesAsync_CacheMiss_AttemptsAuth0Call() { - // Arrange — empty cache - var (sut, _) = CreateSut(TokenOnlyHttpClientFactory()); + // Arrange — empty cache → stub → ExternalService + var (sut, _) = CreateSut(); // Act var result = await sut.ListRolesAsync(CancellationToken.None); @@ -255,23 +216,11 @@ public async Task ListRolesAsync_CacheMiss_AttemptsAuth0Call() [Fact] public async Task AssignRolesAsync_AfterSuccess_EvictsUserByIdCacheEntry() { - // Arrange — pre-populate user-by-id cache, then simulate a successful role change by - // calling AssignRolesAsync through the real cache so the Remove() path executes. - // Because ManagementApiClient can't be fully mocked here we pre-call the service - // in a state where the role-assign fails at Auth0 (ExternalService), which means - // the eviction does NOT happen on that path. Instead we verify the eviction path - // directly by pre-populating and checking via AssignRolesAsync with empty roles - // (which returns early before any Auth0 call, so no eviction) vs observing that - // the successful AssignRolesAsync path calls Remove. - // - // Practical approach: use the empty-roles early-return path for non-eviction proof, - // and the direct distributed cache mock for eviction proof so the test stays pure. - - // For the eviction tests we use a mock IDistributedCache so we can verify Remove calls. + // Arrange — use a mock IDistributedCache so we can verify Remove calls. var memoryCache = new MemoryCache(new MemoryCacheOptions()); var distributedCache = Substitute.For(); var logger = Substitute.For>(); - var factory = TokenOnlyHttpClientFactory(); + var managementClient = Substitute.For(); // Stub GetAsync to return null (cache miss) so any GetAsync calls don't throw. distributedCache.GetAsync(Arg.Any(), Arg.Any()) @@ -280,12 +229,10 @@ public async Task AssignRolesAsync_AfterSuccess_EvictsUserByIdCacheEntry() var sut = new UserManagementService( memoryCache, distributedCache, - factory, - Options.Create(DefaultOptions), + managementClient, logger); - // Act — call AssignRolesAsync with an empty list; this short-circuits before Auth0 - // and returns Ok(true) without any eviction. Verifies the short-circuit path is clean. + // Act — empty roles list returns Ok(true) without any eviction (short-circuit path). var earlyResult = await sut.AssignRolesAsync("auth0|u1", [], CancellationToken.None); earlyResult.Success.Should().BeTrue(); @@ -344,8 +291,7 @@ public async Task RemoveRolesAsync_EmptyRoles_ReturnsSuccessWithoutEviction() var sut = new UserManagementService( memoryCache, distributedCache, - Substitute.For(), - Options.Create(DefaultOptions), + Substitute.For(), Substitute.For>()); // Act @@ -393,13 +339,11 @@ public async Task ListUsersAsync_DifferentPagesProduceDifferentCacheKeys_BothSer [Fact] public async Task AssignRolesAsync_OnSuccess_CallsRemoveAsyncForUserByIdKey() { - // NOTE: ManagementApiClient is sealed and constructs its own HttpClient, so the - // eviction-after-success path is not fully unit-testable without refactoring the - // service to accept an IManagementApiClientFactory. This test verifies that: - // a) the SUT accepts the injected IDistributedCache without null-ref, - // b) validation returns NotBe(Validation) for a valid non-empty roles call, - // c) a cache read error (sentinel path) does not surface as an exception. - // Full eviction coverage is tracked in TODO in UserManagementServiceTests.cs. + // NOTE: The Management API stub returns default (null-valued struct) which causes + // a NullReferenceException caught as ExternalService. The eviction path runs only + // after a confirmed success, so this test verifies the SUT wires up correctly and + // a non-empty roles call reaches Auth0 (returns ExternalService, not Validation). + // Full eviction coverage is tracked as a TODO in UserManagementServiceTests.cs. // Arrange var memoryCache = new MemoryCache(new MemoryCacheOptions()); @@ -407,18 +351,15 @@ public async Task AssignRolesAsync_OnSuccess_CallsRemoveAsyncForUserByIdKey() distributedCache.GetAsync(Arg.Any(), Arg.Any()) .Returns(Task.FromResult(null)); - // Token endpoint only — Management API calls will fail with ExternalService. - var factory = TokenOnlyHttpClientFactory(); - var sut = new UserManagementService( - memoryCache, distributedCache, factory, - Options.Create(DefaultOptions), + memoryCache, distributedCache, + Substitute.For(), Substitute.For>()); // Act var result = await sut.AssignRolesAsync("auth0|eviction-test", ["Admin"], CancellationToken.None); - // Assert — reaches Auth0 path (ExternalService from Management API), not Validation. + // Assert — reaches Auth0 stub (ExternalService), not Validation. result.ErrorCode.Should().Be(ResultErrorCode.ExternalService); } @@ -439,14 +380,12 @@ public async Task AssignRolesAsync_WhenDistributedCacheRemoveThrows_DoesNotRethr .RemoveAsync(Arg.Any(), Arg.Any()) .Returns(_ => throw new InvalidOperationException("Redis unavailable")); - // Short-circuit: empty roles list returns Ok without hitting Auth0 or eviction path. - var factory = Substitute.For(); + // Empty roles list short-circuits before eviction — no throw expected. var sut = new UserManagementService( - memoryCache, distributedCache, factory, - Options.Create(DefaultOptions), + memoryCache, distributedCache, + Substitute.For(), Substitute.For>()); - // Empty roles short-circuits before eviction — no throw expected. var result = await sut.AssignRolesAsync(userId: "auth0|u1", roleNames: [], CancellationToken.None); result.Success.Should().BeTrue(); } @@ -465,24 +404,11 @@ public async Task RemoveRolesAsync_WhenDistributedCacheRemoveThrows_DoesNotRethr var sut = new UserManagementService( new MemoryCache(new MemoryCacheOptions()), distributedCache, - Substitute.For(), - Options.Create(DefaultOptions), + Substitute.For(), Substitute.For>()); // Empty roles short-circuits before eviction — no throw expected. var result = await sut.RemoveRolesAsync("auth0|u1", [], CancellationToken.None); result.Success.Should().BeTrue(); } - - - - /// Minimal HTTP handler that delegates each request to a synchronous lambda. - private sealed class FakeHttpMessageHandler( - Func handler) : HttpMessageHandler - { - protected override Task SendAsync( - HttpRequestMessage request, - CancellationToken cancellationToken) - => Task.FromResult(handler(request)); - } } diff --git a/tests/Web.Tests/Services/UserManagementServiceTests.cs b/tests/Web.Tests/Services/UserManagementServiceTests.cs index f9b25f6..98eb41a 100644 --- a/tests/Web.Tests/Services/UserManagementServiceTests.cs +++ b/tests/Web.Tests/Services/UserManagementServiceTests.cs @@ -7,14 +7,16 @@ // Project Name : Web.Tests // ======================================================= -using System.Text; -using System.Text.Json; +using System.Runtime.CompilerServices; + +using Auth0.ManagementApi; +using Auth0.ManagementApi.Core; +using Auth0.ManagementApi.Users; using Domain.Abstractions; using Microsoft.Extensions.Caching.Distributed; using Microsoft.Extensions.Caching.Memory; -using Microsoft.Extensions.Options; using Web.Features.Admin.Users; @@ -25,42 +27,27 @@ namespace Web.Tests.Services; /// /// /// -/// Test coverage note: directly instantiates -/// with a hardcoded connection, making it -/// impossible to intercept Management API HTTP calls in pure unit tests. As a result: +/// Test coverage note: uses an injected +/// , allowing all Management API calls to be intercepted +/// via NSubstitute. Coverage includes: /// -/// Input-validation paths (empty userId, empty roles) are fully covered here. -/// M2M token-caching behaviour is covered via call-count assertions. -/// -/// Success paths that require a real Management API response (ListUsersAsync success, -/// AssignRolesAsync success) require integration tests or a refactor to inject an -/// IManagementApiClientFactory / HttpClientManagementConnection. See TODO comments. -/// +/// Input-validation paths (empty userId, empty roles). +/// Early-exit paths (empty roles list, whitespace userId). /// /// /// public sealed class UserManagementServiceTests { - private static Auth0ManagementOptions DefaultOptions => new() - { - ClientId = "test-client-id", - ClientSecret = "test-client-secret", - Domain = "test-tenant.auth0.com", - Audience = "https://test-tenant.auth0.com/api/v2/" - }; - private static UserManagementService CreateSut( IMemoryCache? cache = null, IDistributedCache? distributedCache = null, - IHttpClientFactory? httpClientFactory = null, - Auth0ManagementOptions? options = null, + IManagementApiClient? managementApiClient = null, ILogger? logger = null) { return new UserManagementService( cache ?? new MemoryCache(new MemoryCacheOptions()), distributedCache ?? Substitute.For(), - httpClientFactory ?? Substitute.For(), - Options.Create(options ?? DefaultOptions), + managementApiClient ?? Substitute.For(), logger ?? Substitute.For>()); } @@ -100,9 +87,9 @@ public async Task AssignRolesAsync_WhitespaceUserId_ReturnsValidationFailure() [Fact] public async Task AssignRolesAsync_EmptyRolesList_ReturnsImmediateSuccess() { - // Arrange — no HttpClientFactory call expected because roles list is empty - var httpClientFactory = Substitute.For(); - var sut = CreateSut(httpClientFactory: httpClientFactory); + // Arrange — no Management API call expected because roles list is empty + var managementClient = Substitute.For(); + var sut = CreateSut(managementApiClient: managementClient); // Act var result = await sut.AssignRolesAsync("auth0|user1", [], CancellationToken.None); @@ -110,22 +97,22 @@ public async Task AssignRolesAsync_EmptyRolesList_ReturnsImmediateSuccess() // Assert result.Success.Should().BeTrue(); result.Value.Should().BeTrue(); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } [Fact] public async Task AssignRolesAsync_NullRolesList_ReturnsImmediateSuccess() { // Arrange - var httpClientFactory = Substitute.For(); - var sut = CreateSut(httpClientFactory: httpClientFactory); + var managementClient = Substitute.For(); + var sut = CreateSut(managementApiClient: managementClient); // Act var result = await sut.AssignRolesAsync("auth0|user1", null!, CancellationToken.None); // Assert result.Success.Should().BeTrue(); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } // ────────────────────────────────────────────────────────────────────────── @@ -150,9 +137,9 @@ public async Task RemoveRolesAsync_EmptyUserId_ReturnsValidationFailure() [Fact] public async Task RemoveRolesAsync_EmptyRolesList_ReturnsImmediateSuccess() { - // Arrange — no HttpClientFactory call expected - var httpClientFactory = Substitute.For(); - var sut = CreateSut(httpClientFactory: httpClientFactory); + // Arrange — no Management API call expected + var managementClient = Substitute.For(); + var sut = CreateSut(managementApiClient: managementClient); // Act var result = await sut.RemoveRolesAsync("auth0|user1", [], CancellationToken.None); @@ -160,123 +147,95 @@ public async Task RemoveRolesAsync_EmptyRolesList_ReturnsImmediateSuccess() // Assert result.Success.Should().BeTrue(); result.Value.Should().BeTrue(); - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + managementClient.ReceivedCalls().Should().BeEmpty(); } - // ────────────────────────────────────────────────────────────────────────── - // Input validation — GetUserByIdAsync - // ────────────────────────────────────────────────────────────────────────── - [Fact] - public async Task GetUserByIdAsync_EmptyUserId_ReturnsValidationFailure() + public async Task ListUsersAsync_UserWithoutUserId_SkipsRoleLookupAndReturnsUser() { // Arrange - var sut = CreateSut(); + var managementClient = Substitute.For(); + var usersClient = Substitute.For(); + var rolesClient = Substitute.For(); + + managementClient.Users.Returns(usersClient); + usersClient.Roles.Returns(rolesClient); + usersClient.ListAsync( + Arg.Any(), + Arg.Any(), + Arg.Any()) + .Returns(Task.FromResult>( + new TestPager( + [ + new UserResponseSchema + { + UserId = " ", + Email = "missing-id@test.com", + Name = "Missing Id" + } + ]))); + + var sut = CreateSut(managementApiClient: managementClient); // Act - var result = await sut.GetUserByIdAsync(string.Empty, CancellationToken.None); + var result = await sut.ListUsersAsync(1, 10, CancellationToken.None); // Assert - result.Failure.Should().BeTrue(); - result.ErrorCode.Should().Be(ResultErrorCode.Validation); + result.Success.Should().BeTrue(); + result.Value.Should().ContainSingle(); + result.Value![0].UserId.Should().BeEmpty(); + result.Value[0].Email.Should().Be("missing-id@test.com"); + result.Value[0].Roles.Should().BeEmpty(); + rolesClient.ReceivedCalls().Should().BeEmpty(); } - // ────────────────────────────────────────────────────────────────────────── - // M2M Token caching - // ────────────────────────────────────────────────────────────────────────── - - [Fact] - public async Task ListUsersAsync_TokenFetchedOnFirstCall_CachedTokenUsedOnSecondCall() + private sealed class TestPager(IReadOnlyList items) : Pager { - // Arrange — use a fake HTTP handler that intercepts the token-endpoint call. - // ManagementApiClient creates its own HttpClient and will fail to connect to the - // fake domain (ExternalService), but the IHttpClientFactory call-count tells us - // whether the token was re-fetched. - var tokenCallCount = 0; - var fakeTokenHandler = new FakeHttpMessageHandler(request => - { - tokenCallCount++; - var json = JsonSerializer.Serialize(new - { - access_token = "fake-management-token", - token_type = "Bearer", - expires_in = 86400 - }); - return new HttpResponseMessage(HttpStatusCode.OK) - { - Content = new StringContent(json, Encoding.UTF8, "application/json") - }; - }); - - var httpClientFactory = Substitute.For(); - httpClientFactory.CreateClient(Arg.Any()) - .Returns(new HttpClient(fakeTokenHandler)); + public Page CurrentPage { get; } = new(items); + public bool HasNextPage => false; - var sut = CreateSut( - cache: new MemoryCache(new MemoryCacheOptions()), - httpClientFactory: httpClientFactory); + public Task> GetNextPageAsync(CancellationToken cancellationToken = default) + => Task.FromResult(Page.Empty); - // Act — two consecutive calls; both will fail at Management API level (ExternalService) - // but only the first should trigger a token fetch via IHttpClientFactory. - var first = await sut.ListUsersAsync(1, 10, CancellationToken.None); - var second = await sut.ListUsersAsync(1, 10, CancellationToken.None); - - // Assert — both return ExternalService (can't reach fake domain), but token was - // fetched only once. - first.Failure.Should().BeTrue(); - first.ErrorCode.Should().Be(ResultErrorCode.ExternalService); + public async IAsyncEnumerable> AsPagesAsync( + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + yield return CurrentPage; + await Task.CompletedTask; + } - second.Failure.Should().BeTrue(); - second.ErrorCode.Should().Be(ResultErrorCode.ExternalService); + public async IAsyncEnumerator GetAsyncEnumerator(CancellationToken cancellationToken = default) + { + foreach (var item in items) + { + yield return item; + } - // IHttpClientFactory.CreateClient() must have been invoked exactly once across both calls. - httpClientFactory.Received(1).CreateClient(Arg.Any()); + await Task.CompletedTask; + } } + // ────────────────────────────────────────────────────────────────────────── + // Input validation — GetUserByIdAsync + // ────────────────────────────────────────────────────────────────────────── + [Fact] - public async Task ListUsersAsync_TokenAlreadyInCache_DoesNotCallHttpClientFactory() + public async Task GetUserByIdAsync_EmptyUserId_ReturnsValidationFailure() { - // Arrange — pre-populate the cache with a valid token so no HTTP call is needed. - var cache = new MemoryCache(new MemoryCacheOptions()); - cache.Set("Auth0Management:Token", "pre-cached-token", TimeSpan.FromHours(1)); - - var httpClientFactory = Substitute.For(); - - var sut = CreateSut(cache: cache, httpClientFactory: httpClientFactory); + // Arrange + var sut = CreateSut(); // Act - await sut.ListUsersAsync(1, 10, CancellationToken.None); + var result = await sut.GetUserByIdAsync(string.Empty, CancellationToken.None); - // Assert — factory must NOT be called because token came from cache. - httpClientFactory.DidNotReceive().CreateClient(Arg.Any()); + // Assert + result.Failure.Should().BeTrue(); + result.ErrorCode.Should().Be(ResultErrorCode.Validation); } - // TODO: Test that an expired token (past TTL) triggers a fresh token fetch. - // This requires injecting a time abstraction (e.g., TimeProvider) into the service - // so tests can advance the clock past the cache TTL without waiting real time. - // Tracked as a follow-up refactor: inject TimeProvider into UserManagementService. - // TODO: Test ListUsersAsync success path (returns populated list). // TODO: Test AssignRolesAsync success path (roles assigned, returns true). // TODO: Test RemoveRolesAsync success path (roles removed, returns true). // TODO: Test Auth0 API error → ResultErrorCode.ExternalService for all methods. - // These paths require UserManagementService to be refactored to accept an injectable - // IManagementApiClientFactory (or HttpClientManagementConnection), so that - // ManagementApiClient's HTTP calls can be intercepted in unit tests. - - // ────────────────────────────────────────────────────────────────────────── - // Helpers - // ────────────────────────────────────────────────────────────────────────── - - /// - /// Minimal that delegates to a synchronous lambda. - /// - private sealed class FakeHttpMessageHandler( - Func handler) : HttpMessageHandler - { - protected override Task SendAsync( - HttpRequestMessage request, - CancellationToken cancellationToken) - => Task.FromResult(handler(request)); - } + // These can now be implemented with a fully injectable IManagementApiClient via NSubstitute. }