@hoanghainh/komagu 2.1.1 → 2.2.0

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

@@ -0,0 +1,233 @@
+namespace Komagu.Security.Authorization.Tests;
+
+using System.Security.Claims;
+using Komagu.Security.AspNetCore;
+using Komagu.Security.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Abstractions;
+using Microsoft.AspNetCore.Mvc.Filters;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using Microsoft.Extensions.Primitives;
+using Moq;
+using Xunit;
+
+public class RoleAuthorizationFilterTests
+{
+    private static ClaimsPrincipal Authenticated(string roleClaimType = ClaimTypes.Role, params string[] roles)
+    {
+        var claims = new List<Claim> { new("sub", "user-1"), new("tenant_id", "tenant-1") };
+        claims.AddRange(roles.Select(r => new Claim(roleClaimType, r)));
+        return new ClaimsPrincipal(new ClaimsIdentity(claims, "TestAuth"));
+    }
+
+    private static AuthorizationFilterContext CreateContext(
+        ClaimsPrincipal user,
+        Dictionary<string, object?>? routeValues = null,
+        Action<HttpRequest>? configureRequest = null)
+    {
+        var httpContext = new DefaultHttpContext { User = user };
+        configureRequest?.Invoke(httpContext.Request);
+
+        var routeData = new RouteData();
+        foreach (var (k, v) in routeValues ?? new Dictionary<string, object?>())
+        {
+            routeData.Values[k] = v;
+        }
+
+        var actionContext = new ActionContext(httpContext, routeData, new ActionDescriptor { DisplayName = "AdminController.DeleteUser" });
+        return new AuthorizationFilterContext(actionContext, new List<IFilterMetadata>());
+    }
+
+    private static RoleAuthorizationFilter CreateFilter(
+        string[] roles,
+        ISecurityAuditSink? sink = null,
+        KomaguRoleOptions? options = null)
+    {
+        sink ??= Mock.Of<ISecurityAuditSink>();
+        return new RoleAuthorizationFilter(
+            roles,
+            sink,
+            new DefaultKomaguAuthorizationService(Mock.Of<ISecurityAuditSink>()),
+            Options.Create(options ?? new KomaguRoleOptions()));
+    }
+
+    [Fact]
+    public async Task Filter_WhenCallerHasOneOfRequiredRoles_AllowsRequest()
+    {
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "support"));
+        var filter = CreateFilter(["admin", "support"]);
+
+        await filter.OnAuthorizationAsync(context);
+
+        Assert.Null(context.Result);
+    }
+
+    [Fact]
+    public async Task Filter_WhenCallerLacksRole_ReturnsHttp403()
+    {
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "customer"));
+        var filter = CreateFilter(["admin"]);
+
+        await filter.OnAuthorizationAsync(context);
+
+        var result = Assert.IsType<StatusCodeResult>(context.Result);
+        Assert.Equal(StatusCodes.Status403Forbidden, result.StatusCode);
+    }
+
+    [Fact]
+    public async Task Filter_RoleMatchIsExactAndOrdinal()
+    {
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "Admin", "administrator", " admin"));
+        var filter = CreateFilter(["admin"]);
+
+        await filter.OnAuthorizationAsync(context);
+
+        Assert.IsType<StatusCodeResult>(context.Result);
+    }
+
+    [Fact]
+    public async Task Filter_WhenDenyWithNotFound_ReturnsHttp404()
+    {
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "customer"));
+        var filter = CreateFilter(["admin"], options: new KomaguRoleOptions { DenyWith = RoleDenyResponse.NotFound });
+
+        await filter.OnAuthorizationAsync(context);
+
+        Assert.IsType<NotFoundResult>(context.Result);
+    }
+
+    [Fact]
+    public async Task Filter_WhenCallerIsAnonymous_ReturnsHttp401()
+    {
+        var context = CreateContext(new ClaimsPrincipal(new ClaimsIdentity([new Claim(ClaimTypes.Role, "admin")])));
+        var filter = CreateFilter(["admin"]);
+
+        await filter.OnAuthorizationAsync(context);
+
+        Assert.IsType<UnauthorizedResult>(context.Result);
+    }
+
+    [Fact]
+    public async Task Filter_IgnoresRoleSuppliedInQueryFormRouteAndHeader()
+    {
+        // Invariant: role=admin in the query string, form, route values or an X-Role header never grants the role
+        var context = CreateContext(
+            Authenticated(ClaimTypes.Role, "customer"),
+            routeValues: new Dictionary<string, object?> { ["role"] = "admin" },
+            configureRequest: request =>
+            {
+                request.QueryString = new QueryString("?role=admin&isAdmin=true");
+                request.ContentType = "application/x-www-form-urlencoded";
+                request.Form = new FormCollection(new Dictionary<string, StringValues> { ["role"] = "admin" });
+                request.Headers["X-Role"] = "admin";
+                request.Headers["X-User-Role"] = "admin";
+            });
+        var filter = CreateFilter(["admin"]);
+
+        await filter.OnAuthorizationAsync(context);
+
+        var result = Assert.IsType<StatusCodeResult>(context.Result);
+        Assert.Equal(StatusCodes.Status403Forbidden, result.StatusCode);
+    }
+
+    [Fact]
+    public async Task Filter_UsesConfiguredRoleClaimType()
+    {
+        var jwtUser = Authenticated("role", "admin");
+        var options = new KomaguRoleOptions { RoleClaimType = "role" };
+
+        var allowed = CreateContext(jwtUser);
+        await CreateFilter(["admin"], options: options).OnAuthorizationAsync(allowed);
+        Assert.Null(allowed.Result);
+
+        // With the default ClaimTypes.Role the raw "role" claim is not consulted
+        var denied = CreateContext(jwtUser);
+        await CreateFilter(["admin"]).OnAuthorizationAsync(denied);
+        Assert.IsType<StatusCodeResult>(denied.Result);
+    }
+
+    [Fact]
+    public async Task Filter_OnDenial_EmitsRoleDeniedAuditEvent()
+    {
+        SecurityAuditEvent? captured = null;
+        var sink = new Mock<ISecurityAuditSink>();
+        sink.Setup(s => s.EmitAsync(It.IsAny<SecurityAuditEvent>(), It.IsAny<CancellationToken>()))
+            .Callback<SecurityAuditEvent, CancellationToken>((e, _) => captured = e)
+            .Returns(ValueTask.CompletedTask);
+
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "customer"));
+        await CreateFilter(["admin", "auditor"], sink.Object).OnAuthorizationAsync(context);
+
+        sink.Verify(s => s.EmitAsync(It.IsAny<SecurityAuditEvent>(), It.IsAny<CancellationToken>()), Times.Once);
+        Assert.NotNull(captured);
+        Assert.Equal("Komagu.Authorization.RoleDenied", captured!.EventName);
+        Assert.Equal(RoleAuthorizationFilter.RoleDeniedEventName, captured.EventName);
+        Assert.Equal("user-1", captured.ActorUserId);
+        Assert.Equal("tenant-1", captured.ActorTenantId);
+        Assert.Equal("AdminController.DeleteUser", captured.ResourceId);
+        Assert.Contains("admin", captured.Reason, StringComparison.Ordinal);
+        Assert.Contains("auditor", captured.Reason, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task Filter_OnAllow_DoesNotEmitAuditEvent()
+    {
+        var sink = new Mock<ISecurityAuditSink>();
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "admin"));
+
+        await CreateFilter(["admin"], sink.Object).OnAuthorizationAsync(context);
+
+        sink.Verify(s => s.EmitAsync(It.IsAny<SecurityAuditEvent>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task Filter_WhenAuditSinkThrows_StillDenies()
+    {
+        var sink = new Mock<ISecurityAuditSink>();
+        sink.Setup(s => s.EmitAsync(It.IsAny<SecurityAuditEvent>(), It.IsAny<CancellationToken>()))
+            .Throws(new InvalidOperationException("sink down"));
+        var context = CreateContext(Authenticated(ClaimTypes.Role, "customer"));
+
+        await CreateFilter(["admin"], sink.Object).OnAuthorizationAsync(context);
+
+        Assert.IsType<StatusCodeResult>(context.Result);
+    }
+
+    [Fact]
+    public void Attribute_WithNoRoles_ThrowsArgumentException()
+    {
+        Assert.Throws<ArgumentException>(() => new RequireRoleAttribute());
+        Assert.Throws<ArgumentException>(() => new RequireRoleAttribute(Array.Empty<string>()));
+        Assert.Throws<ArgumentException>(() => new RequireRoleAttribute("admin", " "));
+    }
+
+    [Fact]
+    public async Task Attribute_CreatesFilterFromDi_WithConfiguredOptions()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddKomaguAuthorization();
+        services.ConfigureKomaguRoles(o =>
+        {
+            o.RoleClaimType = "role";
+            o.DenyWith = RoleDenyResponse.NotFound;
+        });
+        using var provider = services.BuildServiceProvider();
+        using var scope = provider.CreateScope();
+
+        var attribute = new RequireRoleAttribute("admin");
+        Assert.Equal(new[] { "admin" }, attribute.Roles);
+        var filter = Assert.IsType<RoleAuthorizationFilter>(attribute.CreateInstance(scope.ServiceProvider));
+
+        var allowed = CreateContext(Authenticated("role", "admin"));
+        await filter.OnAuthorizationAsync(allowed);
+        Assert.Null(allowed.Result);
+
+        var denied = CreateContext(Authenticated("role", "customer"));
+        await filter.OnAuthorizationAsync(denied);
+        Assert.IsType<NotFoundResult>(denied.Result);
+    }
+}

package/remediate/authz/golang/massassign.go

@@ -0,0 +1,16 @@
+package golang
+
+// Mass-assignment defense: copy only allow-listed fields from client input.
+
+// AllowFields returns a new map holding only the allowed keys that are present
+// in src. src is never modified; a nil src yields an empty, non-nil map.
+// Values are copied shallowly (nested maps and slices are shared with src).
+func AllowFields(src map[string]any, allowed ...string) map[string]any {
+	out := make(map[string]any, len(allowed))
+	for _, key := range allowed {
+		if val, ok := src[key]; ok {
+			out[key] = val
+		}
+	}
+	return out
+}

package/remediate/authz/golang/massassign_test.go

@@ -0,0 +1,135 @@
+package golang
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestAllowFields(t *testing.T) {
+	cases := []struct {
+		name    string
+		src     map[string]any
+		allowed []string
+		want    map[string]any
+	}{
+		{
+			name:    "picks allowed keys only",
+			src:     map[string]any{"name": "Ann", "email": "a@x.io", "role": "admin", "is_admin": true},
+			allowed: []string{"name", "email"},
+			want:    map[string]any{"name": "Ann", "email": "a@x.io"},
+		},
+		{
+			name:    "skips allowed keys missing from src",
+			src:     map[string]any{"name": "Ann"},
+			allowed: []string{"name", "email"},
+			want:    map[string]any{"name": "Ann"},
+		},
+		{
+			name:    "keys are case-sensitive",
+			src:     map[string]any{"Name": "Ann"},
+			allowed: []string{"name"},
+			want:    map[string]any{},
+		},
+		{name: "nil src returns empty map", src: nil, allowed: []string{"name"}, want: map[string]any{}},
+		{name: "no allowed keys returns empty map", src: map[string]any{"name": "Ann"}, want: map[string]any{}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := AllowFields(tc.src, tc.allowed...)
+			if got == nil {
+				t.Fatalf("expected non-nil map")
+			}
+			if !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("expected %v, got %v", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestAllowFields_DoesNotMutateSource(t *testing.T) {
+	src := map[string]any{"name": "Ann", "role": "admin"}
+	out := AllowFields(src, "name")
+	out["name"] = "changed"
+	out["extra"] = 1
+
+	want := map[string]any{"name": "Ann", "role": "admin"}
+	if !reflect.DeepEqual(src, want) {
+		t.Fatalf("src was mutated: %v", src)
+	}
+}
+
+// --- DTO allow-list example -------------------------------------------------
+
+// User is the domain model; Role and IsAdmin must never be set from client input.
+type User struct {
+	ID      string
+	Name    string
+	Email   string
+	Role    string
+	IsAdmin bool
+}
+
+// ProfileUpdate is the narrow request DTO: only the fields a user may change.
+type ProfileUpdate struct {
+	Name  string `json:"name"`
+	Email string `json:"email"`
+}
+
+// decodeProfileUpdate rejects any field outside the DTO (strict mode).
+func decodeProfileUpdate(body string) (ProfileUpdate, error) {
+	var dto ProfileUpdate
+	dec := json.NewDecoder(strings.NewReader(body))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&dto); err != nil {
+		return ProfileUpdate{}, err
+	}
+	return dto, nil
+}
+
+// applyProfileUpdate copies DTO fields explicitly and returns a new User.
+func applyProfileUpdate(u User, dto ProfileUpdate) User {
+	u.Name = dto.Name
+	u.Email = dto.Email
+	return u
+}
+
+func TestDTOAllowList_StrictDecodeRejectsPrivilegedFields(t *testing.T) {
+	for _, body := range []string{
+		`{"name":"Ann","role":"admin"}`,
+		`{"name":"Ann","is_admin":true}`,
+		`{"name":"Ann","IsAdmin":true}`,
+	} {
+		if _, err := decodeProfileUpdate(body); err == nil {
+			t.Fatalf("expected strict decode to reject %s", body)
+		}
+	}
+}
+
+func TestDTOAllowList_ExplicitCopyCannotEscalate(t *testing.T) {
+	current := User{ID: "u1", Name: "Old", Email: "old@x.io", Role: "user", IsAdmin: false}
+	body := `{"name":"Ann","email":"ann@x.io","role":"admin","is_admin":true}`
+
+	// Lenient decode into the narrow DTO: unknown fields are dropped, not applied.
+	var dto ProfileUpdate
+	if err := json.Unmarshal([]byte(body), &dto); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	updated := applyProfileUpdate(current, dto)
+
+	if updated.Role != "user" || updated.IsAdmin {
+		t.Fatalf("privileged fields reached the domain model: %+v", updated)
+	}
+	if updated.Name != "Ann" || updated.Email != "ann@x.io" {
+		t.Fatalf("allowed fields not applied: %+v", updated)
+	}
+	if current.Name != "Old" {
+		t.Fatalf("original user was mutated: %+v", current)
+	}
+
+	// Strict decode of the same body fails outright.
+	if _, err := decodeProfileUpdate(body); err == nil {
+		t.Fatalf("expected strict decode to reject privileged fields")
+	}
+}

package/remediate/authz/golang/roles.go

@@ -0,0 +1,168 @@
+package golang
+
+// Komagu Function-Level Authorization (BFLA defense) for Go.
+//
+// RequireRole guards an http.Handler so that only callers holding at least
+// one of the required roles reach it. Caller identity and roles are read
+// ONLY from the trusted Identity that the authentication layer placed in
+// the request context via WithIdentity. Roles are never read from the
+// request body, query string, path or headers.
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// RoleDeniedEventName is the audit event name emitted when RequireRole denies a caller.
+const RoleDeniedEventName = "Komagu.Authorization.RoleDenied"
+
+// Identity is the verified caller identity produced by authentication.
+type Identity struct {
+	UserID   string
+	TenantID string
+	Roles    []string
+}
+
+// HasAnyRole reports whether the identity holds at least one of roles.
+// Matching is exact and case-sensitive.
+func (id Identity) HasAnyRole(roles ...string) bool {
+	for _, held := range id.Roles {
+		for _, want := range roles {
+			if held == want {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+const identityContextKey contextKey = "komaguIdentity"
+
+// WithIdentity returns a copy of ctx carrying id. Call it from authentication
+// middleware after the token or session has been verified. The Roles slice is
+// copied so later changes by the caller do not affect the stored identity.
+func WithIdentity(ctx context.Context, id Identity) context.Context {
+	stored := Identity{
+		UserID:   id.UserID,
+		TenantID: id.TenantID,
+		Roles:    append([]string(nil), id.Roles...),
+	}
+	return context.WithValue(ctx, identityContextKey, stored)
+}
+
+// IdentityFromContext returns the identity stored by WithIdentity. The second
+// result is false when no identity is present or its UserID is blank.
+func IdentityFromContext(ctx context.Context) (Identity, bool) {
+	id, ok := ctx.Value(identityContextKey).(Identity)
+	if !ok || strings.TrimSpace(id.UserID) == "" {
+		return Identity{}, false
+	}
+	id.Roles = append([]string(nil), id.Roles...)
+	return id, true
+}
+
+type roleConfig struct {
+	denyStatus int
+	sink       AuditSink
+}
+
+// RoleOption configures RequireRole.
+type RoleOption func(*roleConfig)
+
+// WithDenyStatus sets the status returned when the caller lacks the role.
+// Only http.StatusForbidden (default) and http.StatusNotFound (hides the
+// endpoint) are accepted; any other value makes RequireRole panic.
+func WithDenyStatus(status int) RoleOption {
+	return func(c *roleConfig) { c.denyStatus = status }
+}
+
+// WithRoleAuditSink sets the sink that receives RoleDenied events.
+// A nil sink falls back to LoggingAuditSink.
+func WithRoleAuditSink(sink AuditSink) RoleOption {
+	return func(c *roleConfig) { c.sink = sink }
+}
+
+// RequireRole returns net/http middleware that allows the request only when
+// the context Identity holds at least one of roles (exact, case-sensitive).
+//
+//   - no Identity in context -> 401 {"error":"unauthorized"}
+//   - Identity without a required role -> 403 {"error":"forbidden"}, or
+//     404 {"error":"resource not found"} with WithDenyStatus(http.StatusNotFound),
+//     and a RoleDeniedEventName audit event.
+//
+// RequireRole panics at construction (route registration) when roles is
+// empty, contains a blank role, or WithDenyStatus is not 403 or 404.
+func RequireRole(roles []string, opts ...RoleOption) func(http.Handler) http.Handler {
+	required := validateRoles(roles)
+	cfg := roleConfig{denyStatus: http.StatusForbidden}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(&cfg)
+		}
+	}
+	if cfg.denyStatus != http.StatusForbidden && cfg.denyStatus != http.StatusNotFound {
+		panic(fmt.Sprintf("komagu: RequireRole deny status must be 403 or 404, got %d", cfg.denyStatus))
+	}
+	if cfg.sink == nil {
+		cfg.sink = &LoggingAuditSink{}
+	}
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			id, ok := IdentityFromContext(r.Context())
+			if !ok {
+				http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
+				return
+			}
+			if !id.HasAnyRole(required...) {
+				emitRoleDenial(cfg.sink, id, r, required)
+				writeRoleDenial(w, cfg.denyStatus)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// RequireRole is RequireRole using the Authorizer's audit sink. An explicit
+// WithRoleAuditSink option still takes precedence.
+func (a *Authorizer) RequireRole(roles []string, opts ...RoleOption) func(http.Handler) http.Handler {
+	all := append([]RoleOption{WithRoleAuditSink(a.Sink)}, opts...)
+	return RequireRole(roles, all...)
+}
+
+func validateRoles(roles []string) []string {
+	if len(roles) == 0 {
+		panic("komagu: RequireRole needs at least one role")
+	}
+	for _, role := range roles {
+		if strings.TrimSpace(role) == "" {
+			panic("komagu: RequireRole roles must not be blank")
+		}
+	}
+	return append([]string(nil), roles...)
+}
+
+func writeRoleDenial(w http.ResponseWriter, status int) {
+	if status == http.StatusNotFound {
+		http.Error(w, `{"error":"resource not found"}`, http.StatusNotFound)
+		return
+	}
+	http.Error(w, `{"error":"forbidden"}`, http.StatusForbidden)
+}
+
+func emitRoleDenial(sink AuditSink, id Identity, r *http.Request, required []string) {
+	sink.Emit(SecurityAuditEvent{
+		Timestamp:     time.Now().UTC(),
+		EventName:     RoleDeniedEventName,
+		ActorUserID:   id.UserID,
+		ActorTenantID: id.TenantID,
+		ResourceType:  "HTTPEndpoint",
+		ResourceID:    r.URL.Path,
+		Operation:     ResourceOperation(r.Method),
+		Reason:        fmt.Sprintf("Caller lacks required role; requires any of [%s]", strings.Join(required, ", ")),
+	})
+}