@hoanghainh/komagu 2.1.1 → 2.2.0

package/remediate/authz/nodejs/src/service.js

@@ -128,6 +128,36 @@ class KomaguSecurityService {
     }
   }
 
+  /**
+   * Emit a 'Komagu.Authorization.RoleDenied' audit event (function-level / BFLA denial).
+   * Auditing failures never affect the denial outcome.
+   */
+  async emitRoleDenial(user, requiredRoles, route, reason = 'Caller lacks required role') {
+    try {
+      let actorUserId = null;
+      let actorTenantId = null;
+
+      if (user) {
+        try { actorUserId = this.getCurrentUserId(user); } catch (_) {}
+        try { actorTenantId = this.getCurrentTenantId(user); } catch (_) {}
+      }
+
+      const event = {
+        timestamp: new Date().toISOString(),
+        eventName: 'Komagu.Authorization.RoleDenied',
+        actorUserId: actorUserId || undefined,
+        actorTenantId: actorTenantId || undefined,
+        requiredRoles: Array.isArray(requiredRoles) ? requiredRoles.slice() : [],
+        route: route || undefined,
+        reason,
+      };
+
+      await this.auditSink.emit(event);
+    } catch (_) {
+      // Auditing failures must never affect the denial outcome
+    }
+  }
+
   async _emitDenial(user, resource, operation, reason, resourceId) {
     try {
       let actorUserId = null;

package/remediate/authz/nodejs/tests/test-authz.js

@@ -253,3 +253,7 @@ test('KomaguSecurityService: claim semantics and edge cases', async () => {
   const decision = await service.authorize(userWithId, emptyOwnerRes, ResourceOperation.READ);
   assert.strictEqual(decision.succeeded, false);
 });
+
+// Role guard (BFLA) and mass-assignment tests. Loaded from here so the CI step
+// `node --test remediate/authz/nodejs/tests/test-authz.js` also runs them.
+require('./test-roles.js');

package/remediate/authz/nodejs/tests/test-roles.js

@@ -0,0 +1,278 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const {
+  NotFoundException,
+  UnauthorizedException,
+  ForbiddenException,
+  InMemorySecurityAuditSink,
+  KomaguSecurityService,
+  RequireRole,
+  KomaguRoleGuard,
+  requireRole,
+  allowFields,
+} = require('../src/index');
+
+function mockRes() {
+  return {
+    statusCode: null,
+    body: null,
+    status(code) {
+      this.statusCode = code;
+      return this;
+    },
+    json(data) {
+      this.body = data;
+      return this;
+    },
+  };
+}
+
+async function runMiddleware(mw, req) {
+  const res = mockRes();
+  let nextCalled = false;
+  await mw(req, res, () => { nextCalled = true; });
+  return { res, nextCalled };
+}
+
+const admin = { userId: 'user-admin', tenantId: 'tenant-komagu', roles: ['admin'] };
+const plainUser = { userId: 'user-b', tenantId: 'tenant-komagu', roles: ['user'] };
+
+// ---------------------------------------------------------------------------
+// Express requireRole
+// ---------------------------------------------------------------------------
+
+test('Express requireRole: allows caller holding a required role (roles array or role string)', async () => {
+  const mw = requireRole(['admin', 'ops']);
+
+  const fromArray = await runMiddleware(mw, { user: admin });
+  assert.strictEqual(fromArray.nextCalled, true);
+  assert.strictEqual(fromArray.res.statusCode, null);
+
+  const fromString = await runMiddleware(mw, { user: { userId: 'user-o', tenantId: 't', role: 'ops' } });
+  assert.strictEqual(fromString.nextCalled, true);
+});
+
+test('Express requireRole: denies with 403 Forbidden by default (case-sensitive match)', async () => {
+  const mw = requireRole('admin', { securityService: new KomaguSecurityService(new InMemorySecurityAuditSink()) });
+
+  const denied = await runMiddleware(mw, { user: plainUser });
+  assert.strictEqual(denied.nextCalled, false);
+  assert.strictEqual(denied.res.statusCode, 403);
+  assert.deepStrictEqual(denied.res.body, { message: 'Forbidden' });
+
+  const wrongCase = await runMiddleware(mw, { user: { userId: 'u', tenantId: 't', roles: ['Admin'] } });
+  assert.strictEqual(wrongCase.res.statusCode, 403);
+});
+
+test('Express requireRole: denyStatus 404 hides the endpoint', async () => {
+  const mw = requireRole('admin', {
+    denyStatus: 404,
+    securityService: new KomaguSecurityService(new InMemorySecurityAuditSink()),
+  });
+  const denied = await runMiddleware(mw, { user: plainUser });
+  assert.strictEqual(denied.nextCalled, false);
+  assert.strictEqual(denied.res.statusCode, 404);
+  assert.deepStrictEqual(denied.res.body, { message: 'Resource not found' });
+});
+
+test('Express requireRole: returns 401 without a principal', async () => {
+  const mw = requireRole('admin');
+  const result = await runMiddleware(mw, { headers: {} });
+  assert.strictEqual(result.nextCalled, false);
+  assert.strictEqual(result.res.statusCode, 401);
+  assert.deepStrictEqual(result.res.body, { message: 'Unauthorized' });
+});
+
+test('Express requireRole: role claimed in body, query, params or headers is ignored', async () => {
+  const sink = new InMemorySecurityAuditSink();
+  const mw = requireRole('admin', { securityService: new KomaguSecurityService(sink) });
+
+  const req = {
+    user: { userId: 'user-b', tenantId: 'tenant-komagu' }, // authenticated, no roles
+    body: { role: 'admin', roles: ['admin'], isAdmin: true },
+    query: { role: 'admin', roles: ['admin'] },
+    params: { role: 'admin' },
+    headers: { 'x-role': 'admin', 'x-roles': 'admin' },
+  };
+  const result = await runMiddleware(mw, req);
+  assert.strictEqual(result.nextCalled, false);
+  assert.strictEqual(result.res.statusCode, 403);
+  assert.strictEqual(sink.events.length, 1);
+});
+
+test('Express requireRole: emits RoleDenied audit event on denial only', async () => {
+  const sink = new InMemorySecurityAuditSink();
+  const mw = requireRole(['admin', 'ops'], { securityService: new KomaguSecurityService(sink) });
+
+  await runMiddleware(mw, { user: admin, method: 'DELETE', baseUrl: '/api', route: { path: '/users/:id' } });
+  assert.strictEqual(sink.events.length, 0);
+
+  await runMiddleware(mw, {
+    user: plainUser,
+    method: 'DELETE',
+    baseUrl: '/api',
+    route: { path: '/users/:id' },
+    originalUrl: '/api/users/7?token=secret',
+  });
+  assert.strictEqual(sink.events.length, 1);
+  const event = sink.events[0];
+  assert.strictEqual(event.eventName, 'Komagu.Authorization.RoleDenied');
+  assert.strictEqual(event.actorUserId, 'user-b');
+  assert.strictEqual(event.actorTenantId, 'tenant-komagu');
+  assert.deepStrictEqual(event.requiredRoles, ['admin', 'ops']);
+  assert.strictEqual(event.route, 'DELETE /api/users/:id');
+  assert.ok(event.timestamp);
+});
+
+test('Express requireRole: audit sink failure does not change the denial', async () => {
+  const brokenSink = { emit() { throw new Error('sink down'); } };
+  const mw = requireRole('admin', { securityService: new KomaguSecurityService(brokenSink) });
+  const result = await runMiddleware(mw, { user: plainUser });
+  assert.strictEqual(result.res.statusCode, 403);
+});
+
+test('requireRole / RequireRole: invalid arguments throw at construction time', () => {
+  for (const bad of [undefined, null, '', '   ', [], [''], ['admin', 42], 42, {}]) {
+    assert.throws(() => requireRole(bad), TypeError, `requireRole(${JSON.stringify(bad)})`);
+    assert.throws(() => RequireRole(bad), TypeError, `RequireRole(${JSON.stringify(bad)})`);
+  }
+  for (const badStatus of [401, 500, '404', 0]) {
+    assert.throws(() => requireRole('admin', { denyStatus: badStatus }), /denyStatus must be 403 or 404/);
+    assert.throws(() => RequireRole('admin', { denyStatus: badStatus }), /denyStatus must be 403 or 404/);
+  }
+  assert.doesNotThrow(() => requireRole('admin', { denyStatus: 403 }));
+  assert.doesNotThrow(() => requireRole('admin', { denyStatus: 404 }));
+});
+
+// ---------------------------------------------------------------------------
+// NestJS RequireRole + KomaguRoleGuard
+// ---------------------------------------------------------------------------
+
+function nestContext(controller, handlerName, req) {
+  return {
+    getHandler: () => controller.prototype[handlerName],
+    getClass: () => controller,
+    switchToHttp: () => ({ getRequest: () => req }),
+  };
+}
+
+function decorate(decorator, controller, handlerName) {
+  decorator(controller.prototype, handlerName, Object.getOwnPropertyDescriptor(controller.prototype, handlerName));
+}
+
+test('NestJS KomaguRoleGuard: allows role holder, denies others with 403 and audits', async () => {
+  const sink = new InMemorySecurityAuditSink();
+  const guard = new KomaguRoleGuard(null, new KomaguSecurityService(sink));
+
+  class AdminController {
+    deleteUser() {}
+    publicInfo() {}
+  }
+  decorate(RequireRole('admin'), AdminController, 'deleteUser');
+
+  assert.strictEqual(await guard.canActivate(nestContext(AdminController, 'deleteUser', { user: admin })), true);
+
+  await assert.rejects(
+    guard.canActivate(nestContext(AdminController, 'deleteUser', {
+      user: plainUser,
+      body: { role: 'admin' },
+      query: { roles: ['admin'] },
+      headers: { 'x-role': 'admin' },
+    })),
+    (err) => {
+      assert(err instanceof ForbiddenException);
+      assert.strictEqual(err.getStatus(), 403);
+      return true;
+    }
+  );
+  assert.strictEqual(sink.events.length, 1);
+  assert.strictEqual(sink.events[0].eventName, 'Komagu.Authorization.RoleDenied');
+  assert.strictEqual(sink.events[0].route, 'AdminController.deleteUser');
+  assert.deepStrictEqual(sink.events[0].requiredRoles, ['admin']);
+
+  // Undecorated handler passes through
+  assert.strictEqual(await guard.canActivate(nestContext(AdminController, 'publicInfo', { user: plainUser })), true);
+});
+
+test('NestJS KomaguRoleGuard: class-level decorator, denyStatus 404 and 401', async () => {
+  const guard = new KomaguRoleGuard(null, new KomaguSecurityService(new InMemorySecurityAuditSink()));
+
+  class OpsController {
+    rotateKeys() {}
+  }
+  RequireRole(['ops'], { denyStatus: 404 })(OpsController);
+
+  await assert.rejects(
+    guard.canActivate(nestContext(OpsController, 'rotateKeys', { user: plainUser })),
+    (err) => err instanceof NotFoundException && err.getStatus() === 404
+  );
+  await assert.rejects(
+    guard.canActivate(nestContext(OpsController, 'rotateKeys', {})),
+    (err) => err instanceof UnauthorizedException && err.getStatus() === 401
+  );
+  assert.strictEqual(
+    await guard.canActivate(nestContext(OpsController, 'rotateKeys', { user: { userId: 'o', tenantId: 't', role: 'ops' } })),
+    true
+  );
+});
+
+// ---------------------------------------------------------------------------
+// allowFields (mass assignment)
+// ---------------------------------------------------------------------------
+
+test('allowFields: picks allow-listed keys, skips missing, never mutates source', () => {
+  const source = { name: 'Bob', email: 'b@example.com', role: 'admin', isAdmin: true };
+  const snapshot = JSON.parse(JSON.stringify(source));
+
+  const picked = allowFields(source, ['name', 'email', 'phone']);
+  assert.deepStrictEqual(picked, { name: 'Bob', email: 'b@example.com' });
+  assert.strictEqual(Object.prototype.hasOwnProperty.call(picked, 'phone'), false);
+  assert.notStrictEqual(picked, source);
+  assert.deepStrictEqual(source, snapshot);
+});
+
+test('allowFields: ignores __proto__/constructor/prototype and inherited or non-enumerable keys', () => {
+  const malicious = JSON.parse('{"__proto__": {"isAdmin": true}, "constructor": {"x": 1}, "prototype": 1, "name": "x"}');
+  const picked = allowFields(malicious, ['__proto__', 'constructor', 'prototype', 'name']);
+  assert.deepStrictEqual(Object.keys(picked), ['name']);
+  assert.strictEqual(Object.getPrototypeOf(picked), Object.prototype);
+  assert.strictEqual(picked.isAdmin, undefined);
+  assert.strictEqual({}.isAdmin, undefined);
+
+  const inherited = Object.create({ role: 'admin' });
+  Object.defineProperty(inherited, 'hidden', { value: 'h', enumerable: false });
+  assert.deepStrictEqual(allowFields(inherited, ['role', 'hidden']), {});
+});
+
+test('allowFields: non-object source yields {}; invalid allow-list throws', () => {
+  for (const bad of [undefined, null, 'str', 42, true, ['a']]) {
+    assert.deepStrictEqual(allowFields(bad, ['a', '0']), {});
+  }
+  assert.throws(() => allowFields({ a: 1 }, 'a'), TypeError);
+});
+
+test('DTO allow-list example: profile update cannot change role or isAdmin', async () => {
+  const usersDb = { 'user-b': { id: 'user-b', name: 'Bob', email: 'bob@old.example', role: 'user', isAdmin: false } };
+
+  // Example Express handler: PATCH /me
+  function updateProfile(req, res) {
+    const changes = allowFields(req.body, ['name', 'email']);
+    const current = usersDb[req.user.userId];
+    usersDb[req.user.userId] = { ...current, ...changes };
+    return res.status(200).json(usersDb[req.user.userId]);
+  }
+
+  const res = mockRes();
+  updateProfile({
+    user: { userId: 'user-b', tenantId: 'tenant-komagu' },
+    body: { name: 'Bobby', email: 'bob@new.example', role: 'admin', isAdmin: true, id: 'user-a' },
+  }, res);
+
+  assert.strictEqual(res.statusCode, 200);
+  assert.deepStrictEqual(usersDb['user-b'], {
+    id: 'user-b', name: 'Bobby', email: 'bob@new.example', role: 'user', isAdmin: false,
+  });
+});

package/remediate/authz/spring/build.gradle.kts

@@ -50,6 +50,11 @@ dependencies {
     testImplementation("org.springframework.data:spring-data-commons:3.5.13")
     testImplementation("org.springframework:spring-aspects:6.2.19")
     testImplementation("org.aspectj:aspectjweaver:1.9.25.1")
+    // Test-only: a real servlet request for the role-from-request tests, and Jackson (the version
+    // Spring Boot $springBootVersion manages) for the mass-assignment DTO example.
+    testImplementation("jakarta.servlet:jakarta.servlet-api:6.1.0")
+    testImplementation("com.fasterxml.jackson.core:jackson-databind:2.21.4")
+    testImplementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.21.4")
 }
 
 tasks.test {

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/authorization/SecurityAuditEvent.kt

@@ -7,7 +7,7 @@ import java.time.Instant
  */
 data class SecurityAuditEvent(
     val timestamp: Instant = Instant.now(),
-    val eventName: String = "Komagu.Authorization.Denied",
+    val eventName: String = DENIED,
     val traceId: String? = null,
     val actorUserId: String? = null,
     val actorTenantId: String? = null,
@@ -16,7 +16,15 @@ data class SecurityAuditEvent(
     val operation: ResourceOperation = ResourceOperation.READ,
     val clientIp: String? = null,
     val reason: String = ""
-)
+) {
+    companion object {
+        /** Object-level (ownership / tenant) denial. */
+        const val DENIED = "Komagu.Authorization.Denied"
+
+        /** Function-level denial: the caller lacks every role required by @RequireRole. */
+        const val ROLE_DENIED = "Komagu.Authorization.RoleDenied"
+    }
+}
 
 /**
  * Sink interface for processing security audit events.

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/data/MassAssignment.kt

@@ -0,0 +1,18 @@
+@file:JvmName("MassAssignment")
+
+package io.komagu.security.data
+
+/**
+ * Mass-assignment defense for map-shaped input (e.g. a JSON body bound to `Map<String, Any?>`).
+ *
+ * Returns a NEW map holding only the entries of [source] whose keys are listed in [allowed]
+ * (exact, case-sensitive match, source order kept). [source] is never mutated. Privileged fields such as
+ * `role`, `isAdmin` or `balance` are dropped unless explicitly allowed.
+ *
+ * Prefer a dedicated request DTO that declares only the client-editable fields; use this helper when the
+ * input must stay a map (patch endpoints, legacy controllers).
+ */
+fun allowFields(source: Map<String, Any?>, vararg allowed: String): Map<String, Any?> {
+    val allowedKeys = allowed.toSet()
+    return source.filterKeys { it in allowedKeys }
+}

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/spring/AuthenticationRequiredException.kt

@@ -0,0 +1,14 @@
+package io.komagu.security.spring
+
+import org.springframework.http.HttpStatus
+import org.springframework.web.bind.annotation.ResponseStatus
+
+/**
+ * Thrown when a role-protected method is invoked without an authenticated principal.
+ * Mapped to HTTP 401 Unauthorized.
+ */
+@ResponseStatus(HttpStatus.UNAUTHORIZED, reason = "Authentication required")
+class AuthenticationRequiredException(
+    message: String = "Authentication required",
+    cause: Throwable? = null
+) : RuntimeException(message, cause)

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/spring/KomaguSecurityAutoConfiguration.kt

@@ -8,6 +8,7 @@ import org.springframework.beans.factory.ObjectProvider
 import org.springframework.boot.autoconfigure.AutoConfiguration
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
 import org.springframework.context.annotation.Bean
+import org.springframework.core.env.Environment
 
 /**
  * Spring Boot AutoConfiguration for Komagu Authorization module.
@@ -37,4 +38,23 @@ class KomaguSecurityAutoConfiguration {
     ): OwnershipAspect {
         return OwnershipAspect(securityManager, resolvers.orderedStream().toList())
     }
+
+    /**
+     * Role (function-level) aspect for @RequireRole. Set `komagu.security.role.hide-denied-as-not-found=true`
+     * to answer role denials with 404 instead of 403 for every annotated endpoint.
+     */
+    @Bean
+    @ConditionalOnMissingBean(RoleAspect::class)
+    fun roleAspect(
+        securityManager: KomaguSecurityManager,
+        auditSink: SecurityAuditSink,
+        environment: Environment
+    ): RoleAspect {
+        val hideAsNotFound = environment.getProperty(HIDE_ROLE_DENIED_PROPERTY, Boolean::class.javaObjectType, false)
+        return RoleAspect(securityManager, auditSink, hideAsNotFound)
+    }
+
+    companion object {
+        const val HIDE_ROLE_DENIED_PROPERTY = "komagu.security.role.hide-denied-as-not-found"
+    }
 }

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/spring/RequireRole.kt

@@ -0,0 +1,34 @@
+package io.komagu.security.spring
+
+/**
+ * Declarative function-level authorization (BFLA defense) for controller or service methods and classes.
+ *
+ * The caller is allowed when the authenticated principal in Spring Security's `SecurityContextHolder`
+ * holds at least one of the listed roles. Roles are read only from the principal's granted authorities,
+ * never from request parameters, bodies or headers.
+ *
+ * Role matching rule: a single leading `ROLE_` prefix is stripped from both the granted authority and the
+ * required role, then the names are compared exactly and case-sensitively. So `ROLE_admin` and `admin`
+ * both satisfy `@RequireRole("admin")` (and `@RequireRole("ROLE_admin")`), while `Admin` and `SCOPE_admin`
+ * do not. JWT scopes or custom role claims must be mapped to granted authorities by the application's
+ * `JwtAuthenticationConverter`.
+ *
+ * Outcomes:
+ * - not authenticated: [AuthenticationRequiredException] (HTTP 401);
+ * - authenticated but no matching role: [RoleDeniedException] (HTTP 403), or [ResourceNotFoundException]
+ *   (HTTP 404) when [hideAsNotFound] is true or `komagu.security.role.hide-denied-as-not-found=true`;
+ * - empty or blank role list: [IllegalStateException] before the method runs (misconfiguration, fail fast).
+ *
+ * A method-level annotation takes precedence over a class-level one.
+ *
+ * NOTE ON SPRING PROXY BYPASS (Self-Invocation):
+ * Spring AOP proxies intercept calls entering from outside the bean. Calling an annotated method from
+ * within the same class (`this.method()`) bypasses the proxy and will NOT enforce role checks.
+ */
+@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.RUNTIME)
+@MustBeDocumented
+annotation class RequireRole(
+    vararg val value: String,
+    val hideAsNotFound: Boolean = false
+)

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/spring/RoleAspect.kt

@@ -0,0 +1,97 @@
+package io.komagu.security.spring
+
+import io.komagu.security.authorization.KomaguSecurityManager
+import io.komagu.security.authorization.SecurityAuditEvent
+import io.komagu.security.authorization.SecurityAuditSink
+import org.aspectj.lang.ProceedingJoinPoint
+import org.aspectj.lang.annotation.Around
+import org.aspectj.lang.annotation.Aspect
+import org.aspectj.lang.reflect.MethodSignature
+import org.springframework.security.authentication.AnonymousAuthenticationToken
+import org.springframework.security.core.Authentication
+import org.springframework.security.core.context.SecurityContextHolder
+import java.time.Instant
+
+/**
+ * Spring AOP Aspect enforcing [RequireRole] on annotated methods and classes (BFLA defense).
+ *
+ * Roles come only from the granted authorities of the authentication in `SecurityContextHolder`;
+ * request parameters, bodies and headers are never consulted. See [RequireRole] for the matching rule.
+ *
+ * NOTE ON PROXY BYPASS (Self-Invocation):
+ * Direct calls within the same class bypass the Spring proxy and will NOT trigger this aspect.
+ */
+@Aspect
+class RoleAspect(
+    private val securityManager: KomaguSecurityManager,
+    private val auditSink: SecurityAuditSink,
+    private val hideDeniedAsNotFound: Boolean = false
+) {
+
+    companion object {
+        const val ROLE_PREFIX = "ROLE_"
+
+        /** Strips one leading `ROLE_` prefix; the remaining name is compared case-sensitively. */
+        fun normalizeRole(role: String): String = role.trim().removePrefix(ROLE_PREFIX)
+    }
+
+    @Around("@annotation(io.komagu.security.spring.RequireRole) || @within(io.komagu.security.spring.RequireRole)")
+    fun enforceRole(joinPoint: ProceedingJoinPoint): Any? {
+        val method = (joinPoint.signature as? MethodSignature)?.method
+        val annotation = method?.getAnnotation(RequireRole::class.java)
+            ?: method?.declaringClass?.getAnnotation(RequireRole::class.java)
+            ?: joinPoint.target?.javaClass?.getAnnotation(RequireRole::class.java)
+            ?: return joinPoint.proceed()
+
+        val target = method?.let { "${it.declaringClass.simpleName}.${it.name}" } ?: "method"
+        requireAnyRole(annotation.value.toList(), annotation.hideAsNotFound, target)
+        return joinPoint.proceed()
+    }
+
+    /**
+     * Programmatic check: returns normally when the current principal holds at least one of [roles].
+     * Throws [AuthenticationRequiredException] (401), [RoleDeniedException] (403) or, when
+     * [hideAsNotFound] (or the configured default) is set, [ResourceNotFoundException] (404).
+     */
+    fun requireAnyRole(roles: Collection<String>, hideAsNotFound: Boolean = false, target: String = "method") {
+        val required = roles.map { normalizeRole(it) }
+        check(required.isNotEmpty() && required.none { it.isEmpty() }) {
+            "@RequireRole on '$target' must list at least one non-blank role"
+        }
+
+        val authentication = SecurityContextHolder.getContext().authentication
+        if (authentication == null || !authentication.isAuthenticated ||
+            authentication is AnonymousAuthenticationToken
+        ) {
+            throw AuthenticationRequiredException()
+        }
+
+        val granted = authentication.authorities.orEmpty()
+            .mapNotNull { it.authority }
+            .map { normalizeRole(it) }
+            .toSet()
+        if (required.any { it in granted }) return
+
+        val reason = "Caller lacks required role(s) [${required.joinToString(", ")}] for '$target'"
+        emitRoleDeniedAudit(authentication, target, reason)
+        throw if (hideAsNotFound || hideDeniedAsNotFound) ResourceNotFoundException() else RoleDeniedException()
+    }
+
+    private fun emitRoleDeniedAudit(authentication: Authentication, target: String, reason: String) {
+        try {
+            auditSink.emit(
+                SecurityAuditEvent(
+                    timestamp = Instant.now(),
+                    eventName = SecurityAuditEvent.ROLE_DENIED,
+                    actorUserId = runCatching { securityManager.getCurrentUserId(authentication) }.getOrNull(),
+                    actorTenantId = runCatching { securityManager.getCurrentTenantId(authentication) }.getOrNull(),
+                    resourceType = "Endpoint",
+                    resourceId = target,
+                    reason = reason
+                )
+            )
+        } catch (_: Exception) {
+            // Auditing failures must never alter the denial outcome
+        }
+    }
+}

package/remediate/authz/spring/src/main/kotlin/io/komagu/security/spring/RoleDeniedException.kt

@@ -0,0 +1,14 @@
+package io.komagu.security.spring
+
+import org.springframework.http.HttpStatus
+import org.springframework.web.bind.annotation.ResponseStatus
+
+/**
+ * Thrown when an authenticated caller lacks every role required by [RequireRole].
+ * Mapped to HTTP 403 Forbidden. Use `hideAsNotFound` to answer 404 instead and hide the endpoint.
+ */
+@ResponseStatus(HttpStatus.FORBIDDEN, reason = "Forbidden")
+class RoleDeniedException(
+    message: String = "Forbidden",
+    cause: Throwable? = null
+) : RuntimeException(message, cause)

package/remediate/authz/spring/src/test/kotlin/io/komagu/security/KomaguSecurityAutoConfigurationTest.kt

@@ -2,7 +2,14 @@ package io.komagu.security
 
 import io.komagu.security.spring.KomaguSecurityAutoConfiguration
 import io.komagu.security.spring.OwnershipAspect
+import io.komagu.security.spring.ResourceNotFoundException
 import io.komagu.security.spring.ResourceOwnershipResolver
+import io.komagu.security.spring.RoleAspect
+import io.komagu.security.spring.RoleDeniedException
+import org.junit.jupiter.api.AfterEach
+import org.junit.jupiter.api.assertThrows
+import org.springframework.security.authentication.TestingAuthenticationToken
+import org.springframework.security.core.context.SecurityContextHolder
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
 import org.springframework.boot.autoconfigure.AutoConfigurations
@@ -35,4 +42,31 @@ class KomaguSecurityAutoConfigurationTest {
                 assertThat(context).hasSingleBean(OwnershipAspect::class.java)
             }
     }
+
+    @AfterEach
+    fun clear() = SecurityContextHolder.clearContext()
+
+    @Test
+    fun `role aspect is auto-configured and denies with 403 by default`() {
+        contextRunner.run { context ->
+            assertThat(context).hasNotFailed()
+            assertThat(context).hasSingleBean(RoleAspect::class.java)
+            SecurityContextHolder.getContext().authentication = TestingAuthenticationToken("u", null, "ROLE_user")
+            assertThrows<RoleDeniedException> {
+                context.getBean(RoleAspect::class.java).requireAnyRole(listOf("admin"))
+            }
+        }
+    }
+
+    @Test
+    fun `role denial maps to 404 when the hide property is set`() {
+        contextRunner
+            .withPropertyValues("${KomaguSecurityAutoConfiguration.HIDE_ROLE_DENIED_PROPERTY}=true")
+            .run { context ->
+                SecurityContextHolder.getContext().authentication = TestingAuthenticationToken("u", null, "ROLE_user")
+                assertThrows<ResourceNotFoundException> {
+                    context.getBean(RoleAspect::class.java).requireAnyRole(listOf("admin"))
+                }
+            }
+    }
 }