@hoanghainh/komagu 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@hoanghainh/komagu` (published as `komainu-guard` up to v1.7.0) are documented here. From v1.2.2 on, entries are generated by [release-please](https://github.com/googleapis/release-please) from [Conventional Commits](https://www.conventionalcommits.org/). Earlier entries are copied from the [GitHub Releases](https://github.com/hoanghainh1188/komainu/releases).
 
+## [2.2.0](https://github.com/hoanghainh1188/komagu/compare/v2.1.2...v2.2.0) (2026-11-01)
+
+
+### Features
+
+* **remediate:** add role guards and DTO allow-list helpers for BFLA and mass assignment ([#337](https://github.com/hoanghainh1188/komagu/issues/337)) ([e8c0463](https://github.com/hoanghainh1188/komagu/commit/e8c046322fa10c3c29a5d896cdbb41de65282c34))
+
 ## [2.1.2](https://github.com/hoanghainh1188/komagu/compare/v2.1.1...v2.1.2) (2026-11-01)
 
 

package/assess/lsa/knowledge/bfla-patterns.md

@@ -89,3 +89,11 @@ route named `/orders/close-month` can still be an admin function.
 
 Adjust with `severity-and-cwe.md` (multi-tenant impact +1, compensating
 control outside code −1).
+
+## 7. Recommended fix
+
+Check the role on the server, from the authenticated principal only, before the privileged action.
+Komagu ships a drop-in guard per stack (`[RequireRole]` for .NET, `@RequireRole` for Spring Boot,
+`requireRole` / `@RequireRole` for Express and NestJS, `RequireRole` middleware for Go): see
+`remediate/authz/README.md`, section 7. Use it in the finding's `recommendation` when the target stack
+matches; never suggest reading the role from the request.

package/assess/lsa/knowledge/mass-assignment-patterns.md

@@ -75,3 +75,10 @@ Bindings to DTO or form classes that are not entities are not reported.
 | Only harmless fields reachable | low (or no finding) |
 
 Adjust with `severity-and-cwe.md`.
+
+## 6. Recommended fix
+
+Bind a DTO with only the editable fields and copy them onto the entity explicitly, or filter map-shaped
+input with an allow-list. Komagu has a tested example per stack and an `allowFields` helper for Spring
+Boot, Express and Go: see `remediate/authz/README.md`, section 7. Use it in the finding's `recommendation`
+when the target stack matches.

package/operate/cli/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "2.1.2"  # x-release-please-version
+__version__ = "2.2.0"  # x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoanghainh/komagu",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Security-First Legacy Modernization Platform CLI (LSA Kit, IAM Perimeter, Cross-User Testing)",
   "main": "remediate/authz/nodejs/src/index.js",
   "types": "remediate/authz/nodejs/src/index.d.ts",

package/remediate/authz/README.md

@@ -276,7 +276,128 @@ func RegisterOrderRoutes(mux *http.ServeMux, authorizer *authz.Authorizer) {
 
 ---
 
-## 7. Test Verification & D5 Runner
+## 7. Function-Level Authorization (BFLA) and Mass Assignment
+
+These helpers fix the two privilege findings of the audit kit: **BFLA** (CWE-285, see
+[`bfla-patterns.md`](../../assess/lsa/knowledge/bfla-patterns.md)) and **mass assignment** (CWE-915, see
+[`mass-assignment-patterns.md`](../../assess/lsa/knowledge/mass-assignment-patterns.md)).
+
+The role guard behaves the same in every module:
+
+| Rule | Behaviour |
+|---|---|
+| Role source | The authenticated principal only (claims, granted authorities, `req.user`, request context). Never route values, query, form, body or headers |
+| Not authenticated | 401 |
+| Match | The caller needs at least one of the listed roles (exact, case-sensitive) |
+| Denied | 403 by default; a module setting answers 404 to hide the endpoint |
+| Audit | Each denial emits `Komagu.Authorization.RoleDenied` with actor ids and the required roles |
+| Bad configuration | Empty or blank role lists and unsupported deny statuses fail fast |
+
+For mass assignment, bind a DTO that lists only the fields the caller may change and copy them onto the
+entity explicitly. Never bind the entity itself or rely on `[Bind(Include = "...")]`. Where the input is a
+map, `allowFields` keeps only the listed keys and never mutates its input.
+
+### .NET 8
+
+```csharp
+// Program.cs
+builder.Services.AddKomaguAuthorization();
+builder.Services.ConfigureKomaguRoles(o =>
+{
+    o.RoleClaimType = "role";               // default: ClaimTypes.Role
+    o.DenyWith = RoleDenyResponse.NotFound; // default: Forbidden (403)
+});
+
+[HttpDelete("admin/users/{id}")]
+[RequireRole("admin", "support")]           // any one role; several attributes must all pass
+public IActionResult DeleteUser(int id) => NoContent();
+
+public sealed record ProfileUpdateDto(string Name, string Email)
+{
+    public void ApplyTo(Customer customer)
+    {
+        customer.Name = Name;
+        customer.Email = Email;             // Role / IsAdmin / Balance cannot be set from the request
+    }
+}
+```
+
+`[RequireRole]` is an authorization filter, so it runs before model binding.
+
+### Spring Boot 3
+
+```kotlin
+@RestController
+@RequestMapping("/admin")
+@RequireRole("admin")                                       // class-level default
+class AdminController(private val users: UserService) {
+    @DeleteMapping("/users/{id}")
+    fun delete(@PathVariable id: String) = users.delete(id) // ROLE_admin or admin passes
+
+    @GetMapping("/audit")
+    @RequireRole("admin", "auditor", hideAsNotFound = true) // method-level overrides class-level
+    fun audit() = users.auditTrail()
+}
+
+data class ProfileUpdate(val name: String, val email: String) {
+    fun applyTo(account: UserAccount) = account.copy(name = name, email = email)
+}
+val safe = allowFields(body, "name", "email")               // io.komagu.security.data
+```
+
+Roles are the granted authorities of the authentication in `SecurityContextHolder`; one leading `ROLE_` is
+ignored on both sides. Map JWT scopes or role claims to authorities in your `JwtAuthenticationConverter`.
+Set `komagu.security.role.hide-denied-as-not-found=true` to answer every denial with 404. Spring Boot's
+default `ObjectMapper` silently drops unknown fields such as `role`; the explicit copy is what keeps them out.
+
+### Node.js (Express & NestJS)
+
+```js
+const { requireRole, allowFields } = require('@hoanghainh/komagu-authz');
+
+app.delete('/admin/users/:id', requireRole('admin'), deleteUser);
+app.post('/ops/rotate-keys', requireRole(['ops', 'admin'], { denyStatus: 404 }), rotateKeys);
+
+app.patch('/me', async (req, res) => {
+  const changes = allowFields(req.body, ['name', 'email']); // role / isAdmin are dropped
+  res.json(await users.update(req.user.userId, changes));
+});
+```
+
+```ts
+@Controller('admin')
+@UseGuards(KomaguRoleGuard)
+export class AdminController {
+  @Delete('users/:id')
+  @RequireRole('admin')
+  deleteUser(@Param('id') id: string) { /* ... */ }
+}
+```
+
+Roles come from `req.user.roles` and `req.user.role`. `allowFields` ignores `__proto__`, `constructor` and
+`prototype`, and copies values by reference.
+
+### Go
+
+```go
+// After verifying the token, attach the identity in your authentication middleware.
+ctx := authz.WithIdentity(r.Context(), authz.Identity{UserID: claims.Sub, TenantID: claims.TenantID, Roles: claims.Roles})
+
+auth := authz.NewAuthorizer(nil)
+mux.Handle("/admin/users", authenticate(auth.RequireRole([]string{"admin"})(adminUsers)))
+mux.Handle("/internal/reindex", authenticate(auth.RequireRole(
+    []string{"admin", "ops"}, authz.WithDenyStatus(http.StatusNotFound))(reindex)))
+
+patch := authz.AllowFields(body, "name", "email")           // or decode into a narrow struct:
+dec := json.NewDecoder(r.Body)
+dec.DisallowUnknownFields()                                 // {"role":"admin"} -> 400
+```
+
+`RequireRole` panics at route registration on an empty role list or a deny status other than 403 / 404.
+
+---
+
+## 8. Test Verification & D5 Runner
 
 All multi-language adapters verify identical BOLA defense invariants:
 

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/KomaguRoleOptions.cs

@@ -0,0 +1,20 @@
+namespace Komagu.Security.AspNetCore;
+
+using System.Security.Claims;
+
+/// <summary>
+/// Options for <see cref="RequireRoleAttribute"/> / <see cref="RoleAuthorizationFilter"/>.
+/// </summary>
+public sealed class KomaguRoleOptions
+{
+    /// <summary>
+    /// Claim type read from the authenticated <see cref="ClaimsPrincipal"/> to obtain the caller's roles.
+    /// Defaults to <see cref="ClaimTypes.Role"/>; set to <c>"role"</c> or <c>"roles"</c> for raw JWT claims.
+    /// </summary>
+    public string RoleClaimType { get; set; } = ClaimTypes.Role;
+
+    /// <summary>
+    /// Response returned when an authenticated caller lacks every required role. Defaults to 403 Forbidden.
+    /// </summary>
+    public RoleDenyResponse DenyWith { get; set; } = RoleDenyResponse.Forbidden;
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RequireRoleAttribute.cs

@@ -0,0 +1,34 @@
+namespace Komagu.Security.AspNetCore;
+
+using Microsoft.AspNetCore.Mvc;
+
+/// <summary>
+/// Declarative function-level authorization (BFLA defense): the authenticated caller must hold at least one of the
+/// given roles. Roles are read only from verified <c>HttpContext.User</c> claims, never from the request.
+/// Returns 401 when unauthenticated and 403 (or 404, see <see cref="KomaguRoleOptions.DenyWith"/>) when denied.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
+public sealed class RequireRoleAttribute : TypeFilterAttribute
+{
+    public RequireRoleAttribute(params string[] roles)
+        : base(typeof(RoleAuthorizationFilter))
+    {
+        if (roles == null || roles.Length == 0)
+        {
+            throw new ArgumentException("At least one required role must be specified.", nameof(roles));
+        }
+
+        if (roles.Any(string.IsNullOrWhiteSpace))
+        {
+            throw new ArgumentException("Required roles must not be null, empty or whitespace.", nameof(roles));
+        }
+
+        Roles = roles.ToArray();
+        Arguments = new object[] { Roles.ToArray() };
+    }
+
+    /// <summary>
+    /// Roles accepted by this guard; holding any one of them (exact, ordinal match) grants access.
+    /// </summary>
+    public IReadOnlyList<string> Roles { get; }
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RoleAuthorizationFilter.cs

@@ -0,0 +1,114 @@
+namespace Komagu.Security.AspNetCore;
+
+using System.Diagnostics;
+using Komagu.Security.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+using Microsoft.Extensions.Options;
+
+/// <summary>
+/// Authorization filter enforcing that the authenticated caller holds at least one required role.
+/// Runs before model binding, so request-supplied values (route, query, form, body, headers) can never grant a role.
+/// </summary>
+public sealed class RoleAuthorizationFilter : IAsyncAuthorizationFilter
+{
+    /// <summary>
+    /// Audit event name emitted on a role denial.
+    /// </summary>
+    public const string RoleDeniedEventName = "Komagu.Authorization.RoleDenied";
+
+    private readonly string[] _requiredRoles;
+    private readonly ISecurityAuditSink _auditSink;
+    private readonly IKomaguAuthorizationService _authorizationService;
+    private readonly KomaguRoleOptions _options;
+
+    public RoleAuthorizationFilter(
+        string[] requiredRoles,
+        ISecurityAuditSink auditSink,
+        IKomaguAuthorizationService authorizationService,
+        IOptions<KomaguRoleOptions> options)
+    {
+        ArgumentNullException.ThrowIfNull(requiredRoles);
+        if (requiredRoles.Length == 0 || requiredRoles.Any(string.IsNullOrWhiteSpace))
+        {
+            throw new ArgumentException("At least one non-empty required role must be specified.", nameof(requiredRoles));
+        }
+
+        _requiredRoles = requiredRoles.ToArray();
+        _auditSink = auditSink ?? throw new ArgumentNullException(nameof(auditSink));
+        _authorizationService = authorizationService ?? throw new ArgumentNullException(nameof(authorizationService));
+        _options = options?.Value ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    public async Task OnAuthorizationAsync(AuthorizationFilterContext context)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        var user = context.HttpContext.User;
+
+        // Invariant: Unauthenticated callers get 401 before any role evaluation
+        if (user?.Identity?.IsAuthenticated != true)
+        {
+            context.Result = new UnauthorizedResult();
+            return;
+        }
+
+        // Roles come only from the verified principal; exact, ordinal match against any required role
+        var roleClaimType = string.IsNullOrWhiteSpace(_options.RoleClaimType)
+            ? System.Security.Claims.ClaimTypes.Role
+            : _options.RoleClaimType;
+
+        var hasRole = user.FindAll(roleClaimType)
+            .Any(c => _requiredRoles.Contains(c.Value, StringComparer.Ordinal));
+
+        if (hasRole)
+        {
+            return;
+        }
+
+        context.Result = _options.DenyWith == RoleDenyResponse.NotFound
+            ? new NotFoundResult()
+            : new StatusCodeResult(StatusCodes.Status403Forbidden);
+
+        await EmitDenialAsync(context).ConfigureAwait(false);
+    }
+
+    private async ValueTask EmitDenialAsync(AuthorizationFilterContext context)
+    {
+        var httpContext = context.HttpContext;
+        try
+        {
+            var auditEvent = new SecurityAuditEvent
+            {
+                Timestamp = DateTimeOffset.UtcNow,
+                EventName = RoleDeniedEventName,
+                TraceId = Activity.Current?.Id ?? httpContext.TraceIdentifier,
+                ActorUserId = TryRead(() => _authorizationService.GetCurrentUserId(httpContext.User)),
+                ActorTenantId = TryRead(() => _authorizationService.GetCurrentTenantId(httpContext.User)),
+                ResourceType = "Endpoint",
+                ResourceId = context.ActionDescriptor?.DisplayName ?? httpContext.Request.Path.Value,
+                ClientIp = httpContext.Connection.RemoteIpAddress?.ToString(),
+                Reason = $"Missing required role: caller holds none of [{string.Join(", ", _requiredRoles)}]"
+            };
+
+            await _auditSink.EmitAsync(auditEvent, httpContext.RequestAborted).ConfigureAwait(false);
+        }
+        catch
+        {
+            // Auditing failures must not mask or alter the denial outcome
+        }
+    }
+
+    private static string? TryRead(Func<string> read)
+    {
+        try
+        {
+            return read();
+        }
+        catch (UnauthorizedAccessException)
+        {
+            return null;
+        }
+    }
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RoleDenyResponse.cs

@@ -0,0 +1,17 @@
+namespace Komagu.Security.AspNetCore;
+
+/// <summary>
+/// HTTP response returned by <see cref="RoleAuthorizationFilter"/> when an authenticated caller lacks every required role.
+/// </summary>
+public enum RoleDenyResponse
+{
+    /// <summary>
+    /// HTTP 403 Forbidden (default).
+    /// </summary>
+    Forbidden,
+
+    /// <summary>
+    /// HTTP 404 Not Found, hiding the existence of the privileged endpoint.
+    /// </summary>
+    NotFound
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/ServiceCollectionExtensions.cs

@@ -16,6 +16,7 @@ public static class ServiceCollectionExtensions
     {
         services.TryAddSingleton<ISecurityAuditSink, LoggingSecurityAuditSink>();
         services.TryAddScoped<IKomaguAuthorizationService, DefaultKomaguAuthorizationService>();
+        services.AddOptions<KomaguRoleOptions>();
         return services;
     }
 
@@ -27,6 +28,21 @@ public static class ServiceCollectionExtensions
     {
         services.AddSingleton<ISecurityAuditSink, TAuditSink>();
         services.TryAddScoped<IKomaguAuthorizationService, DefaultKomaguAuthorizationService>();
+        services.AddOptions<KomaguRoleOptions>();
+        return services;
+    }
+
+    /// <summary>
+    /// Configures the <see cref="RequireRoleAttribute"/> guard (role claim type, 403 vs 404 on denial).
+    /// Call after <c>AddKomaguAuthorization</c>.
+    /// </summary>
+    public static IServiceCollection ConfigureKomaguRoles(
+        this IServiceCollection services,
+        Action<KomaguRoleOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configure);
+        services.AddOptions<KomaguRoleOptions>().Configure(configure);
         return services;
     }
 }

package/remediate/authz/dotnet/tests/Komagu.Security.Authorization.Tests/MassAssignmentDtoTests.cs

@@ -0,0 +1,76 @@
+namespace Komagu.Security.Authorization.Tests;
+
+using System.Text.Json;
+using Xunit;
+
+/// <summary>
+/// Mass-assignment remediation example: replace whole-entity binding (or <c>[Bind(Include = "...")]</c>) with a
+/// request DTO that declares only the client-editable fields, then copy them onto the tracked entity explicitly.
+/// </summary>
+public class MassAssignmentDtoTests
+{
+    /// <summary>Persisted entity: Role, IsAdmin and Balance must never be client-writable.</summary>
+    public sealed class Customer
+    {
+        public int Id { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public string Email { get; set; } = string.Empty;
+        public string Role { get; set; } = "customer";
+        public bool IsAdmin { get; set; }
+        public decimal Balance { get; set; }
+    }
+
+    /// <summary>Allow-list DTO: only the fields a customer may edit on their own profile.</summary>
+    public sealed record ProfileUpdateDto(string Name, string Email)
+    {
+        /// <summary>Explicit copy: privileged fields are not reachable from the request.</summary>
+        public void ApplyTo(Customer customer)
+        {
+            ArgumentNullException.ThrowIfNull(customer);
+            customer.Name = Name;
+            customer.Email = Email;
+        }
+    }
+
+    private static readonly JsonSerializerOptions WebJson = new(JsonSerializerDefaults.Web);
+
+    [Fact]
+    public void ProfileUpdate_WithPrivilegedFieldsInJson_ChangesOnlyAllowListedFields()
+    {
+        var customer = new Customer { Id = 7, Name = "Old", Email = "old@example.com", Role = "customer", IsAdmin = false, Balance = 10m };
+        const string attackerJson = """
+            {"id": 1, "name": "New Name", "email": "new@example.com", "role": "admin", "isAdmin": true, "balance": 999999}
+            """;
+
+        var dto = JsonSerializer.Deserialize<ProfileUpdateDto>(attackerJson, WebJson);
+        Assert.NotNull(dto);
+        dto!.ApplyTo(customer);
+
+        Assert.Equal("New Name", customer.Name);
+        Assert.Equal("new@example.com", customer.Email);
+        Assert.Equal(7, customer.Id);
+        Assert.Equal("customer", customer.Role);
+        Assert.False(customer.IsAdmin);
+        Assert.Equal(10m, customer.Balance);
+    }
+
+    [Fact]
+    public void ProfileUpdateDto_ExposesOnlyNameAndEmail()
+    {
+        var writable = typeof(ProfileUpdateDto).GetProperties().Select(p => p.Name).OrderBy(n => n, StringComparer.Ordinal);
+        Assert.Equal(new[] { "Email", "Name" }, writable);
+    }
+
+    [Fact]
+    public void WholeEntityBinding_IsTheVulnerablePattern()
+    {
+        // Contrast: deserializing straight into the entity lets the client set Role/IsAdmin/Balance.
+        const string attackerJson = """{"name": "x", "email": "x@example.com", "role": "admin", "isAdmin": true, "balance": 999999}""";
+
+        var bound = JsonSerializer.Deserialize<Customer>(attackerJson, WebJson)!;
+
+        Assert.Equal("admin", bound.Role);
+        Assert.True(bound.IsAdmin);
+        Assert.Equal(999999m, bound.Balance);
+    }
+}