@hoanghainh/komagu 2.1.2 → 2.2.1

package/remediate/authz/golang/roles_test.go

@@ -0,0 +1,158 @@
+package golang
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func okHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+func withCaller(req *http.Request, id Identity) *http.Request {
+	return req.WithContext(WithIdentity(req.Context(), id))
+}
+
+var (
+	adminCaller  = Identity{UserID: "user-admin", TenantID: "tenant-komagu", Roles: []string{"admin"}}
+	regularUser  = Identity{UserID: "user-b", TenantID: "tenant-komagu", Roles: []string{"user"}}
+	upperCaseFan = Identity{UserID: "user-c", TenantID: "tenant-komagu", Roles: []string{"Admin"}}
+)
+
+func TestRequireRole_Decisions(t *testing.T) {
+	cases := []struct {
+		name   string
+		roles  []string
+		opts   []RoleOption
+		caller *Identity
+		want   int
+	}{
+		{"allowed with required role", []string{"admin"}, nil, &adminCaller, http.StatusOK},
+		{"allowed with any of several roles", []string{"ops", "admin"}, nil, &adminCaller, http.StatusOK},
+		{"denied 403 by default", []string{"admin"}, nil, &regularUser, http.StatusForbidden},
+		{"denied 404 when hiding endpoint", []string{"admin"}, []RoleOption{WithDenyStatus(http.StatusNotFound)}, &regularUser, http.StatusNotFound},
+		{"role match is case-sensitive", []string{"admin"}, nil, &upperCaseFan, http.StatusForbidden},
+		{"unauthenticated 401", []string{"admin"}, nil, nil, http.StatusUnauthorized},
+		{"blank user id treated as unauthenticated", []string{"admin"}, nil, &Identity{UserID: "  ", Roles: []string{"admin"}}, http.StatusUnauthorized},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			opts := append([]RoleOption{WithRoleAuditSink(&InMemoryAuditSink{})}, tc.opts...)
+			handler := RequireRole(tc.roles, opts...)(okHandler())
+			req := httptest.NewRequest(http.MethodDelete, "/admin/users/42", nil)
+			if tc.caller != nil {
+				req = withCaller(req, *tc.caller)
+			}
+			rec := httptest.NewRecorder()
+			handler.ServeHTTP(rec, req)
+			if rec.Code != tc.want {
+				t.Fatalf("expected %d, got %d", tc.want, rec.Code)
+			}
+		})
+	}
+}
+
+func TestRequireRole_IgnoresRoleClaimsFromRequest(t *testing.T) {
+	sink := &InMemoryAuditSink{}
+	handler := RequireRole([]string{"admin"}, WithRoleAuditSink(sink))(okHandler())
+
+	body := strings.NewReader(`{"role":"admin","roles":["admin"],"is_admin":true}`)
+	req := httptest.NewRequest(http.MethodPost, "/admin/users?role=admin&roles=admin", body)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Role", "admin")
+	req.Header.Set("X-Roles", "admin")
+	req = withCaller(req, regularUser)
+
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("expected 403 despite role=admin in query, body and X-Role header, got %d", rec.Code)
+	}
+	if len(sink.Events) != 1 {
+		t.Fatalf("expected 1 audit event, got %d", len(sink.Events))
+	}
+}
+
+func TestRequireRole_EmitsAuditEventOnDenial(t *testing.T) {
+	sink := &InMemoryAuditSink{}
+	auth := NewAuthorizer(sink)
+	handler := auth.RequireRole([]string{"admin", "ops"})(okHandler())
+
+	req := withCaller(httptest.NewRequest(http.MethodDelete, "/admin/users/42", nil), regularUser)
+	handler.ServeHTTP(httptest.NewRecorder(), req)
+
+	if len(sink.Events) != 1 {
+		t.Fatalf("expected 1 audit event, got %d", len(sink.Events))
+	}
+	ev := sink.Events[0]
+	if ev.EventName != "Komagu.Authorization.RoleDenied" {
+		t.Fatalf("unexpected event name %q", ev.EventName)
+	}
+	if ev.ActorUserID != "user-b" || ev.ActorTenantID != "tenant-komagu" {
+		t.Fatalf("unexpected actor %q/%q", ev.ActorUserID, ev.ActorTenantID)
+	}
+	if !strings.Contains(ev.Reason, "admin") || !strings.Contains(ev.Reason, "ops") {
+		t.Fatalf("reason should name required roles, got %q", ev.Reason)
+	}
+	if ev.Operation != ResourceOperation(http.MethodDelete) || ev.ResourceID != "/admin/users/42" {
+		t.Fatalf("unexpected operation/resource %q %q", ev.Operation, ev.ResourceID)
+	}
+	if ev.Timestamp.IsZero() {
+		t.Fatalf("expected timestamp")
+	}
+}
+
+func TestRequireRole_NoAuditOnAllowOrUnauthenticated(t *testing.T) {
+	sink := &InMemoryAuditSink{}
+	handler := RequireRole([]string{"admin"}, WithRoleAuditSink(sink))(okHandler())
+
+	handler.ServeHTTP(httptest.NewRecorder(), withCaller(httptest.NewRequest(http.MethodGet, "/admin", nil), adminCaller))
+	handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/admin", nil))
+	if len(sink.Events) != 0 {
+		t.Fatalf("expected 0 audit events, got %d", len(sink.Events))
+	}
+}
+
+func TestRequireRole_InvalidConfigurationPanics(t *testing.T) {
+	cases := []struct {
+		name  string
+		roles []string
+		opts  []RoleOption
+	}{
+		{"nil roles", nil, nil},
+		{"empty roles", []string{}, nil},
+		{"blank role", []string{"admin", " "}, nil},
+		{"deny status 401", []string{"admin"}, []RoleOption{WithDenyStatus(http.StatusUnauthorized)}},
+		{"deny status 200", []string{"admin"}, []RoleOption{WithDenyStatus(http.StatusOK)}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			defer func() {
+				if recover() == nil {
+					t.Fatalf("expected panic")
+				}
+			}()
+			RequireRole(tc.roles, tc.opts...)
+		})
+	}
+}
+
+func TestIdentity_ContextCopiesRoles(t *testing.T) {
+	roles := []string{"user"}
+	req := withCaller(httptest.NewRequest(http.MethodGet, "/", nil), Identity{UserID: "u1", Roles: roles})
+	roles[0] = "admin" // caller mutates its slice after storing
+
+	got, ok := IdentityFromContext(req.Context())
+	if !ok || got.HasAnyRole("admin") {
+		t.Fatalf("stored identity must not change when the original slice is mutated: %+v", got)
+	}
+	got.Roles[0] = "admin" // reader mutates the returned copy
+	again, _ := IdentityFromContext(req.Context())
+	if again.HasAnyRole("admin") {
+		t.Fatalf("returned identity must be a copy")
+	}
+}

package/remediate/authz/nodejs/src/express/role-middleware.d.ts

@@ -0,0 +1,14 @@
+import { KomaguSecurityService } from '../service';
+
+export type RoleDenyStatus = 403 | 404;
+
+export interface RequireRoleOptions {
+  /** 403 Forbidden (default) or 404 Resource not found to hide the endpoint. */
+  denyStatus?: RoleDenyStatus;
+  securityService?: KomaguSecurityService;
+}
+
+export declare function requireRole(
+  roles: string | readonly string[],
+  options?: RequireRoleOptions
+): (req: any, res: any, next: (err?: any) => void) => Promise<void>;

package/remediate/authz/nodejs/src/express/role-middleware.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { KomaguSecurityService } = require('../service');
+const { normalizeRequiredRoles, resolveDenyStatus, hasAnyRole, denyBody } = require('../roles');
+
+const defaultService = new KomaguSecurityService();
+
+function describeRoute(req) {
+  const method = req.method ? `${req.method} ` : '';
+  if (req.route && req.route.path) {
+    return `${method}${req.baseUrl || ''}${req.route.path}`;
+  }
+  const raw = req.path || req.originalUrl || req.url;
+  if (!raw) {
+    return undefined;
+  }
+  // Never put the query string into the audit trail
+  return `${method}${String(raw).split('?')[0]}`;
+}
+
+/**
+ * Express middleware enforcing function-level authorization (BFLA).
+ * Roles come only from req.user.roles / req.user.role.
+ *
+ * @param {string|string[]} roles - caller needs at least one of these
+ * @param {Object} [options]
+ * @param {403|404} [options.denyStatus=403] - 404 hides the endpoint
+ * @param {KomaguSecurityService} [options.securityService]
+ */
+function requireRole(roles, options = {}) {
+  const requiredRoles = normalizeRequiredRoles(roles);
+  const denyStatus = resolveDenyStatus(options);
+  const service = options.securityService || defaultService;
+
+  return async function (req, res, next) {
+    const user = req.user;
+    if (!user) {
+      return res.status(401).json({ message: 'Unauthorized' });
+    }
+
+    if (hasAnyRole(user, requiredRoles)) {
+      return next();
+    }
+
+    await service.emitRoleDenial(user, requiredRoles, describeRoute(req));
+    return res.status(denyStatus).json(denyBody(denyStatus));
+  };
+}
+
+module.exports = {
+  requireRole,
+};

package/remediate/authz/nodejs/src/index.d.ts

@@ -4,3 +4,5 @@ export * from './nestjs/decorators';
 export * from './nestjs/guards';
 export * from './nestjs/interceptors';
 export * from './express/middleware';
+export * from './express/role-middleware';
+export * from './mass-assignment';

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

@@ -5,28 +5,43 @@ const {
   HttpException,
   NotFoundException,
   UnauthorizedException,
+  ForbiddenException,
   LoggingSecurityAuditSink,
   InMemorySecurityAuditSink,
 } = require('./interfaces');
 
 const { KomaguSecurityService } = require('./service');
-const { KOMAGU_REQUIRE_OWNERSHIP_KEY, RequireOwnership, CurrentUser } = require('./nestjs/decorators');
-const { OwnershipGuard } = require('./nestjs/guards');
+const {
+  KOMAGU_REQUIRE_OWNERSHIP_KEY,
+  KOMAGU_REQUIRE_ROLE_KEY,
+  RequireOwnership,
+  RequireRole,
+  CurrentUser,
+} = require('./nestjs/decorators');
+const { OwnershipGuard, KomaguRoleGuard } = require('./nestjs/guards');
 const { OwnershipInterceptor } = require('./nestjs/interceptors');
 const { komaguOwnershipMiddleware } = require('./express/middleware');
+const { requireRole } = require('./express/role-middleware');
+const { allowFields } = require('./mass-assignment');
 
 module.exports = {
   ResourceOperation,
   HttpException,
   NotFoundException,
   UnauthorizedException,
+  ForbiddenException,
   LoggingSecurityAuditSink,
   InMemorySecurityAuditSink,
   KomaguSecurityService,
   KOMAGU_REQUIRE_OWNERSHIP_KEY,
+  KOMAGU_REQUIRE_ROLE_KEY,
   RequireOwnership,
+  RequireRole,
   CurrentUser,
   OwnershipGuard,
+  KomaguRoleGuard,
   OwnershipInterceptor,
   komaguOwnershipMiddleware,
+  requireRole,
+  allowFields,
 };

package/remediate/authz/nodejs/src/interfaces.d.ts

@@ -25,8 +25,18 @@ export interface SecurityAuditEvent {
   reason: string;
 }
 
+export interface RoleDeniedAuditEvent {
+  timestamp: string;
+  eventName: 'Komagu.Authorization.RoleDenied';
+  actorUserId?: string;
+  actorTenantId?: string;
+  requiredRoles: string[];
+  route?: string;
+  reason: string;
+}
+
 export interface ISecurityAuditSink {
-  emit(event: SecurityAuditEvent): void | Promise<void>;
+  emit(event: SecurityAuditEvent | RoleDeniedAuditEvent): void | Promise<void>;
 }
 
 export declare class HttpException extends Error {
@@ -45,14 +55,18 @@ export declare class UnauthorizedException extends HttpException {
   constructor(message?: string);
 }
 
+export declare class ForbiddenException extends HttpException {
+  constructor(message?: string);
+}
+
 export declare class LoggingSecurityAuditSink implements ISecurityAuditSink {
   constructor(logger?: any);
-  emit(event: SecurityAuditEvent): void;
+  emit(event: SecurityAuditEvent | RoleDeniedAuditEvent): void;
 }
 
 export declare class InMemorySecurityAuditSink implements ISecurityAuditSink {
-  readonly events: SecurityAuditEvent[];
-  emit(event: SecurityAuditEvent): void;
+  readonly events: Array<SecurityAuditEvent | RoleDeniedAuditEvent>;
+  emit(event: SecurityAuditEvent | RoleDeniedAuditEvent): void;
   clear(): void;
 }
 
@@ -61,5 +75,6 @@ export interface UserPrincipal {
   tenantId: string;
   claims?: Record<string, any>;
   roles?: string[];
+  role?: string;
   isAuthenticated?: boolean;
 }

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

@@ -47,6 +47,15 @@ class UnauthorizedException extends HttpException {
   }
 }
 
+/**
+ * Thrown on function-level (role) denial when the endpoint may be revealed.
+ */
+class ForbiddenException extends HttpException {
+  constructor(message = 'Forbidden') {
+    super(message, 403);
+  }
+}
+
 class LoggingSecurityAuditSink {
   constructor(logger = console) {
     this.logger = logger;
@@ -76,6 +85,7 @@ module.exports = {
   HttpException,
   NotFoundException,
   UnauthorizedException,
+  ForbiddenException,
   LoggingSecurityAuditSink,
   InMemorySecurityAuditSink,
 };

package/remediate/authz/nodejs/src/mass-assignment.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a new plain object holding only the allow-listed own enumerable keys of `source`.
+ * `__proto__`, `constructor` and `prototype` are always ignored; non-object source yields `{}`.
+ */
+export declare function allowFields<T extends object, K extends string>(
+  source: T | null | undefined,
+  allowed: readonly K[]
+): Partial<Pick<T, Extract<K, keyof T>>>;

package/remediate/authz/nodejs/src/mass-assignment.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const BLOCKED_KEYS = Object.freeze(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Mass-assignment guard: copy only allow-listed own enumerable keys.
+ *
+ * - Returns a NEW plain object; `source` is never mutated.
+ * - Keys missing from `source` are skipped (not set to undefined).
+ * - `__proto__`, `constructor` and `prototype` are always ignored.
+ * - Non-object (or array) `source` yields `{}`.
+ * - Values are copied by reference (shallow copy).
+ *
+ * @param {Object} source - untrusted input such as req.body
+ * @param {string[]} allowed - field names the caller may set
+ * @returns {Object}
+ */
+function allowFields(source, allowed) {
+  if (!Array.isArray(allowed)) {
+    throw new TypeError('allowFields: allowed must be an array of field names');
+  }
+  const result = {};
+  if (source === null || typeof source !== 'object' || Array.isArray(source)) {
+    return result;
+  }
+  for (const key of allowed) {
+    if (typeof key !== 'string' || BLOCKED_KEYS.includes(key)) {
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(source, key) &&
+        Object.prototype.propertyIsEnumerable.call(source, key)) {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+module.exports = {
+  allowFields,
+};

package/remediate/authz/nodejs/src/nestjs/decorators.d.ts

@@ -1,6 +1,7 @@
 import { ResourceOperationType } from '../interfaces';
 
 export declare const KOMAGU_REQUIRE_OWNERSHIP_KEY = 'komagu:require_ownership';
+export declare const KOMAGU_REQUIRE_ROLE_KEY = 'komagu:require_role';
 
 export interface RequireOwnershipOptions {
   idParamName?: string;
@@ -13,4 +14,19 @@ export declare function RequireOwnership(
   options?: RequireOwnershipOptions
 ): MethodDecorator & ClassDecorator;
 
+export interface RequireRoleDecoratorOptions {
+  /** 403 Forbidden (default) or 404 Resource not found to hide the endpoint. */
+  denyStatus?: 403 | 404;
+}
+
+export interface RequireRoleMetadata {
+  readonly roles: readonly string[];
+  readonly denyStatus: 403 | 404;
+}
+
+export declare function RequireRole(
+  roles: string | readonly string[],
+  options?: RequireRoleDecoratorOptions
+): MethodDecorator & ClassDecorator;
+
 export declare function CurrentUser(): ParameterDecorator;

package/remediate/authz/nodejs/src/nestjs/decorators.js

@@ -1,8 +1,10 @@
 'use strict';
 
 const { ResourceOperation } = require('../interfaces');
+const { normalizeRequiredRoles, resolveDenyStatus } = require('../roles');
 
 const KOMAGU_REQUIRE_OWNERSHIP_KEY = 'komagu:require_ownership';
+const KOMAGU_REQUIRE_ROLE_KEY = 'komagu:require_role';
 
 // WeakMap fallback when reflect-metadata is not loaded
 const metadataStore = new WeakMap();
@@ -57,6 +59,29 @@ function RequireOwnership(operation = ResourceOperation.READ, options = {}) {
   };
 }
 
+/**
+ * Decorator requiring the caller to hold at least one of `roles` (function-level / BFLA check).
+ * Enforced by KomaguRoleGuard. Roles are validated here, so a bad argument fails at load time.
+ *
+ * @param {string|string[]} roles
+ * @param {Object} [options] - { denyStatus: 403 | 404 }
+ */
+function RequireRole(roles, options = {}) {
+  const meta = Object.freeze({
+    roles: normalizeRequiredRoles(roles),
+    denyStatus: resolveDenyStatus(options),
+  });
+
+  return function (target, propertyKey, descriptor) {
+    if (descriptor && descriptor.value) {
+      setMetadata(KOMAGU_REQUIRE_ROLE_KEY, meta, descriptor.value);
+      return descriptor;
+    }
+    setMetadata(KOMAGU_REQUIRE_ROLE_KEY, meta, target);
+    return target;
+  };
+}
+
 /**
  * Parameter decorator extracting the verified user principal from the request.
  */
@@ -70,7 +95,9 @@ function CurrentUser() {
 
 module.exports = {
   KOMAGU_REQUIRE_OWNERSHIP_KEY,
+  KOMAGU_REQUIRE_ROLE_KEY,
   RequireOwnership,
+  RequireRole,
   CurrentUser,
   setMetadata,
   getMetadata,

package/remediate/authz/nodejs/src/nestjs/guards.d.ts

@@ -4,3 +4,8 @@ export declare class OwnershipGuard {
   constructor(reflector: any, securityService: KomaguSecurityService);
   canActivate(context: any): Promise<boolean>;
 }
+
+export declare class KomaguRoleGuard {
+  constructor(reflector: any, securityService?: KomaguSecurityService);
+  canActivate(context: any): Promise<boolean>;
+}

package/remediate/authz/nodejs/src/nestjs/guards.js

@@ -1,7 +1,9 @@
 'use strict';
 
-const { NotFoundException, UnauthorizedException } = require('../interfaces');
-const { KOMAGU_REQUIRE_OWNERSHIP_KEY, getMetadata } = require('./decorators');
+const { NotFoundException, UnauthorizedException, ForbiddenException } = require('../interfaces');
+const { KOMAGU_REQUIRE_OWNERSHIP_KEY, KOMAGU_REQUIRE_ROLE_KEY, getMetadata } = require('./decorators');
+const { KomaguSecurityService } = require('../service');
+const { hasAnyRole } = require('../roles');
 
 /**
  * NestJS Guard evaluating object-level authorization before route handler execution.
@@ -71,6 +73,71 @@ class OwnershipGuard {
   }
 }
 
+function readMeta(reflector, key, handler, targetClass) {
+  let meta = null;
+  if (reflector && typeof reflector.get === 'function') {
+    meta = reflector.get(key, handler) || reflector.get(key, targetClass);
+  }
+  if (!meta) {
+    meta = (handler && getMetadata(key, handler)) ||
+           (targetClass && getMetadata(key, targetClass));
+  }
+  return meta || null;
+}
+
+function describeOperation(req, handler, targetClass) {
+  if (req && req.method && req.route && req.route.path) {
+    return `${req.method} ${req.baseUrl || ''}${req.route.path}`;
+  }
+  const className = targetClass && targetClass.name;
+  const handlerName = handler && handler.name;
+  if (className && handlerName) {
+    return `${className}.${handlerName}`;
+  }
+  return handlerName || className || undefined;
+}
+
+/**
+ * NestJS Guard enforcing @RequireRole (function-level / BFLA authorization).
+ * Roles are read only from the authenticated principal (req.user.roles / req.user.role).
+ * Method-level @RequireRole overrides class-level.
+ */
+class KomaguRoleGuard {
+  constructor(reflector, securityService) {
+    this.reflector = reflector;
+    this.securityService = securityService || new KomaguSecurityService();
+  }
+
+  async canActivate(context) {
+    const handler = context.getHandler ? context.getHandler() : null;
+    const targetClass = context.getClass ? context.getClass() : null;
+
+    const meta = readMeta(this.reflector, KOMAGU_REQUIRE_ROLE_KEY, handler, targetClass);
+    if (!meta) {
+      return true; // No role requirements on this route
+    }
+
+    const httpContext = context.switchToHttp ? context.switchToHttp() : null;
+    const req = httpContext ? httpContext.getRequest() : context.request;
+
+    if (!req || !req.user) {
+      throw new UnauthorizedException('Unauthorized');
+    }
+
+    if (hasAnyRole(req.user, meta.roles)) {
+      return true;
+    }
+
+    await this.securityService.emitRoleDenial(req.user, meta.roles, describeOperation(req, handler, targetClass));
+
+    if (meta.denyStatus === 404) {
+      throw new NotFoundException('Resource not found');
+    }
+    throw new ForbiddenException('Forbidden');
+  }
+}
+
 module.exports = {
   OwnershipGuard,
+  KomaguRoleGuard,
 };

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

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Shared function-level authorization (BFLA) helpers used by the Express
+ * middleware and the NestJS guard.
+ *
+ * Security invariant: roles are read ONLY from the trusted authenticated
+ * principal (`req.user.roles` / `req.user.role`). Request body, query,
+ * params and headers are never consulted.
+ */
+
+const ALLOWED_DENY_STATUSES = Object.freeze([403, 404]);
+
+/**
+ * Validate and normalize the required roles argument. Throws at construction time.
+ * @param {string|string[]} roles
+ * @returns {string[]} frozen copy of the required roles
+ */
+function normalizeRequiredRoles(roles) {
+  const list = typeof roles === 'string' ? [roles] : roles;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new TypeError('requireRole: roles must be a non-empty string or a non-empty array of strings');
+  }
+  for (const role of list) {
+    if (typeof role !== 'string' || role.trim() === '') {
+      throw new TypeError('requireRole: every role must be a non-empty string');
+    }
+  }
+  return Object.freeze(list.slice());
+}
+
+/**
+ * Validate options.denyStatus (403 default, or 404 to hide the endpoint).
+ * @param {Object} [options]
+ * @returns {number}
+ */
+function resolveDenyStatus(options) {
+  const opts = options || {};
+  if (opts.denyStatus === undefined || opts.denyStatus === null) {
+    return 403;
+  }
+  if (!ALLOWED_DENY_STATUSES.includes(opts.denyStatus)) {
+    throw new TypeError(`requireRole: options.denyStatus must be 403 or 404 (got ${String(opts.denyStatus)})`);
+  }
+  return opts.denyStatus;
+}
+
+/**
+ * Collect the caller's roles from the trusted principal only.
+ * @param {Object} user - req.user
+ * @returns {string[]}
+ */
+function getPrincipalRoles(user) {
+  if (!user || typeof user !== 'object') {
+    return [];
+  }
+  const roles = [];
+  if (Array.isArray(user.roles)) {
+    for (const role of user.roles) {
+      if (typeof role === 'string') {
+        roles.push(role);
+      }
+    }
+  }
+  if (typeof user.role === 'string') {
+    roles.push(user.role);
+  }
+  return roles;
+}
+
+/**
+ * True when the principal holds at least one required role (case-sensitive exact match).
+ */
+function hasAnyRole(user, requiredRoles) {
+  const held = getPrincipalRoles(user);
+  return requiredRoles.some((role) => held.includes(role));
+}
+
+function denyBody(status) {
+  return status === 404 ? { message: 'Resource not found' } : { message: 'Forbidden' };
+}
+
+module.exports = {
+  ALLOWED_DENY_STATUSES,
+  normalizeRequiredRoles,
+  resolveDenyStatus,
+  getPrincipalRoles,
+  hasAnyRole,
+  denyBody,
+};

package/remediate/authz/nodejs/src/service.d.ts

@@ -32,4 +32,10 @@ export declare class KomaguSecurityService {
     operation?: ResourceOperationType,
     options?: AuthorizeOptions
   ): Promise<void>;
+  emitRoleDenial(
+    user: any,
+    requiredRoles: readonly string[],
+    route?: string,
+    reason?: string
+  ): Promise<void>;
 }