@lenne.tech/nest-server 11.27.7 → 11.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.7",
+  "version": "11.28.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -84,41 +84,44 @@
     "@getbrevo/brevo": "3.0.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/apollo": "13.4.2",
-    "@nestjs/common": "11.1.23",
-    "@nestjs/core": "11.1.23",
+    "@nestjs/common": "11.1.28",
+    "@nestjs/core": "11.1.28",
     "@nestjs/graphql": "13.4.2",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.23",
+    "@nestjs/platform-express": "11.1.28",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.2",
     "@nestjs/terminus": "11.1.1",
-    "@nestjs/websockets": "11.1.23",
+    "@nestjs/websockets": "11.1.28",
     "@tus/file-store": "2.1.0",
     "@tus/server": "2.4.1",
-    "@types/supertest": "7.2.0",
+    "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "better-auth": "1.6.23",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
     "cookie-parser": "1.4.7",
+    "cron": "4.4.0",
     "dotenv": "17.4.2",
     "ejs": "5.0.2",
     "express": "5.2.1",
     "graphql": "16.14.0",
-    "graphql-query-complexity": "1.1.0",
+    "graphql-query-complexity": "1.1.1",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
+    "graphql-ws": "6.0.8",
+    "jose": "6.2.1",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.2.0",
-    "mongoose": "9.6.2",
-    "multer": "2.1.1",
+    "mongoose": "9.7.4",
+    "multer": "2.2.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.8",
+    "nodemailer": "9.0.3",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -126,26 +129,27 @@
     "rxjs": "7.8.2",
     "supertest": "7.2.2",
     "ts-morph": "27.0.2",
+    "ws": "8.21.0",
     "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
     "@compodoc/compodoc": "1.2.1",
     "@nestjs/cli": "11.0.21",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.1.23",
+    "@nestjs/testing": "11.1.28",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.40",
+    "@swc/core": "1.15.43",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
-    "@types/multer": "2.1.0",
+    "@types/multer": "2.2.0",
     "@types/node": "25.9.1",
-    "@types/nodemailer": "8.0.0",
+    "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.7",
-    "@vitest/ui": "4.1.7",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/ui": "4.1.10",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
@@ -153,17 +157,17 @@
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
     "oxfmt": "0.51.0",
-    "oxlint": "1.66.0",
+    "oxlint": "1.74.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.22.3",
+    "tsx": "4.23.1",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
-    "vite": "8.0.14",
+    "vite": "8.1.4",
     "vite-plugin-node": "8.0.0",
-    "vitest": "4.1.7"
+    "vitest": "4.1.10"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/common/decorators/restricted.decorator.ts

@@ -21,12 +21,12 @@
  * that is worth doing. Until then, `pnpm run check:swc-tdz` is the mechanical guard.
  * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
  */
-import { UnauthorizedException } from '@nestjs/common';
 import 'reflect-metadata';
 import _ = require('lodash');
 
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
 // Import from the id.helper LEAF, never from db.helper: db.helper imports input.helper, which
 // imports this file back — that cycle is what the extraction removed. See id.helper's docblock.
 import { equalIds, getIncludedIds } from '../helpers/id.helper';
@@ -293,15 +293,32 @@ export function checkRestricted(
         return false;
       }
 
+      // Ownership (S_SELF, S_CREATOR) must be decided from the PERSISTED object, never from `data`.
+      //
+      // On the INPUT path `data` is the caller-supplied DTO, so every ownership claim in it is
+      // attacker-controlled. An authenticated attacker could otherwise unlock an owner-restricted
+      // field on someone ELSE's record just by asserting ownership in the payload — the service
+      // applies the input to the target it was called with, not to the ids in the body:
+      //
+      //   PATCH /users/<victim>  { "id": "<own-id>", "createdBy": "<own-id>", "<restricted>": ... }
+      //
+      // `check()` (input.helper.ts) already reads both from `config.dbObject`; this is the same
+      // check and must agree with it. Where no dbObject exists (e.g. create), ownership cannot be
+      // established — exactly what check() does too.
+      //
+      // On the OUTPUT path there is no attacker-controlled input: `data` IS the persisted object
+      // (and a list yields one `data` per item), so it stays the source of truth there.
+      const owner = config.processType === ProcessType.INPUT ? config.dbObject : data;
+
       // Check access rights
       if (
         roles.includes(RoleEnum.S_EVERYONE) ||
         user?.hasRole?.(roles) ||
         (user?.id && roles.includes(RoleEnum.S_USER)) ||
-        (roles.includes(RoleEnum.S_SELF) && equalIds(data, user)) ||
+        (roles.includes(RoleEnum.S_SELF) && equalIds(owner, user)) ||
         (roles.includes(RoleEnum.S_CREATOR) &&
-          (('createdBy' in data && equalIds(data.createdBy, user)) ||
-            (config.allowCreatorOfParent && !('createdBy' in data) && config.isCreatorOfParent))) ||
+          ((owner && 'createdBy' in owner && equalIds(owner.createdBy, user)) ||
+            (config.allowCreatorOfParent && owner && !('createdBy' in owner) && config.isCreatorOfParent))) ||
         (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified)) ||
         (user?.id && checkRoleAccess(roles, user?.roles, RequestContext.get()?.tenantRole))
       ) {
@@ -365,9 +382,10 @@ export function checkRestricted(
       if (config.debug) {
         console.debug(`The current user has no access rights for ${data.constructor?.name}`);
       }
-      // Throw error
+      // 403 when authenticated, 401 otherwise (see accessDeniedException). The class name stays in
+      // the debug log above — the client gets the translatable ErrorCode the role guards also use.
       if (config.throwError) {
-        throw new UnauthorizedException(`The current user has no access rights for ${data.constructor?.name}`);
+        throw accessDeniedException(user);
       }
       return null;
     }
@@ -393,9 +411,14 @@ export function checkRestricted(
 
     // Check rights
     if (valid) {
-      // Check if data is user or user is creator of data (for nested plain objects)
+      // Check if the parent is the user, or the user created it (for nested plain objects).
+      // Same rule as above: on INPUT the ownership claim must come from the persisted object, not
+      // from the DTO — otherwise a forged `id`/`createdBy` in the payload would propagate a faked
+      // "creator of parent" trust down into every nested object.
+      const parent = config.processType === ProcessType.INPUT ? config.dbObject : data;
       config.isCreatorOfParent =
-        equalIds(data, user) || ('createdBy' in data ? equalIds(data.createdBy, user) : config.isCreatorOfParent);
+        equalIds(parent, user) ||
+        (parent && 'createdBy' in parent ? equalIds(parent.createdBy, user) : config.isCreatorOfParent);
 
       // Check deep
       data[propertyKey] = checkRestricted(data[propertyKey], user, config, processedObjects);
@@ -405,11 +428,10 @@ export function checkRestricted(
           `The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`,
         );
       }
-      // Throw error
+      // 403 when authenticated, 401 otherwise (see accessDeniedException). The field and class name
+      // stay in the debug log above — the client gets the translatable ErrorCode the guards also use.
       if (config.throwError) {
-        throw new UnauthorizedException(
-          `The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`,
-        );
+        throw accessDeniedException(user);
       }
 
       // Remove property

package/src/core/common/exceptions/access-denied.exception.ts

@@ -0,0 +1,49 @@
+import { ForbiddenException, UnauthorizedException } from '@nestjs/common';
+
+import { ErrorCode } from '../../modules/error-code/error-codes';
+
+/**
+ * Creates the access error that matches the requester's auth state (RFC 9110, mirrors RolesGuard):
+ * **403 Forbidden** for authenticated requesters (a permission problem) and **401 Unauthorized**
+ * only when the requester is not authenticated.
+ *
+ * Frontends commonly treat 401 as "session expired" and auto-logout (the `@lenne.tech/nuxt-extensions`
+ * auth interceptor patches `$fetch`/`fetch` globally and does exactly this), so a mere permission
+ * error must never surface as 401 — it would kick a logged-in user out of the whole app.
+ *
+ * This is a **factory, not a class**, on purpose: it returns the *native* Nest exceptions, so
+ * `instanceof ForbiddenException` / `instanceof UnauthorizedException` and `@Catch(...)` filters in
+ * consuming projects keep working, and the REST wire body (which `HttpExceptionLogFilter` builds via
+ * `{ ...exception }`, including `name`) stays identical to what it was before. A custom
+ * `HttpException` subclass would satisfy neither.
+ *
+ * The default messages are the same translatable `ErrorCode`s the role guards throw (`#LTNS_xxxx:`
+ * marker → resolvable by the frontend error-translation layer). Pass an explicit `message` only
+ * where a raw string is genuinely required; prefer logging request-specific detail (class names,
+ * field names) over returning it to the client.
+ *
+ * @param user The **requesting** user (never the target object). The decision key is `user.id`: an
+ *   id that is present — even a falsy one like `0` or `''` — counts as authenticated, while
+ *   `undefined`, `null` or no user at all does not. This mirrors how `check()` defines "logged in"
+ *   (`S_USER` requires `user?.id`).
+ * @param message Overrides the default `ErrorCode`. Omit it to stay consistent with `RolesGuard`.
+ *
+ * @example
+ * // 403 for an authenticated user who lacks a right, 401 for an anonymous requester:
+ * throw accessDeniedException(currentUser);
+ *
+ * @see src/core/modules/auth/guards/roles.guard.ts — the pre-existing 401/403 pattern this mirrors
+ * @see migration-guides/11.27.7-to-11.28.0.md
+ */
+export function accessDeniedException(
+  user: { id?: unknown } | null | undefined,
+  message?: string,
+): ForbiddenException | UnauthorizedException {
+  // A present id means authenticated. `!!user?.id` would misjudge falsy-but-real ids (0, '') as
+  // anonymous and hand an authenticated user the very 401 this mechanism exists to avoid.
+  const authenticated = user?.id !== undefined && user?.id !== null;
+
+  return authenticated
+    ? new ForbiddenException(message ?? ErrorCode.ACCESS_DENIED)
+    : new UnauthorizedException(message ?? ErrorCode.UNAUTHORIZED);
+}

package/src/core/common/helpers/input.helper.ts

@@ -1,4 +1,4 @@
-import { BadRequestException, UnauthorizedException } from '@nestjs/common';
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 import { ValidatorOptions } from 'class-validator/types/validation/ValidatorOptions';
@@ -7,6 +7,8 @@ import { Kind } from 'graphql/index';
 import { checkRestricted } from '../decorators/restricted.decorator';
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
+import { ErrorCode } from '../../modules/error-code/error-codes';
 import { clone } from './clone.helper';
 import { merge } from './config.helper';
 import { equalIds } from './id.helper';
@@ -248,9 +250,11 @@ export async function check(
     }
     let valid = false;
 
-    // Prevent access for everyone, including administrators
+    // Prevent access for everyone, including administrators. Always 403, never 401: the resource is
+    // locked permanently, so authenticating can never grant access and telling an anonymous
+    // requester to "authenticate and retry" (401) would be a lie. Both role guards do the same.
     if (roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException('No access');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Check access
@@ -276,7 +280,8 @@ export async function check(
       valid = true;
     }
     if (!valid) {
-      throw new UnauthorizedException('Missing rights');
+      // 403 when authenticated, 401 otherwise — policy documented in accessDeniedException
+      throw accessDeniedException(user);
     }
   }
 

package/src/core/common/helpers/service.helper.ts

@@ -1,10 +1,10 @@
-import { UnauthorizedException } from '@nestjs/common';
 import bcrypt = require('bcrypt');
 import { sha256 } from 'js-sha256';
 import _ = require('lodash');
 import { Types } from 'mongoose';
 
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
 import { PrepareInputOptions } from '../interfaces/prepare-input-options.interface';
 import { PrepareOutputOptions } from '../interfaces/prepare-output-options.interface';
 import { ResolveSelector } from '../interfaces/resolve-selector.interface';
@@ -151,15 +151,17 @@ export async function prepareInput<T = any>(
     value === undefined && delete input[key];
   }
 
-  // Process roles
+  // Process roles — 403 when authenticated, 401 otherwise (see accessDeniedException). The rejected
+  // roles are logged rather than returned: the client gets the translatable ErrorCode the guards use.
   if (config.checkRoles && (input as Record<string, any>).roles && !currentUser?.hasRole?.(RoleEnum.ADMIN)) {
     if (!(currentUser as any)?.roles) {
-      throw new UnauthorizedException('Missing roles of current user');
+      throw accessDeniedException(currentUser);
     } else {
       const allowedRoles = _.intersection((input as Record<string, any>).roles, (currentUser as any).roles);
       if (allowedRoles.length !== (input as Record<string, any>).roles.length) {
         const missingRoles = _.difference((input as Record<string, any>).roles, (currentUser as any).roles);
-        throw new UnauthorizedException(`Current user not allowed setting roles: ${missingRoles}`);
+        console.debug(`Current user not allowed setting roles: ${missingRoles}`);
+        throw accessDeniedException(currentUser);
       }
       (input as Record<string, any>).roles = allowedRoles;
     }

package/src/core/modules/auth/guards/roles.guard.ts

@@ -137,9 +137,10 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     ]);
     const roles = mergeRolesMetadata(reflectorRoles);
 
-    // Check if locked - always deny
+    // Check if locked - always deny. 403, never 401: the endpoint is locked permanently, so
+    // authenticating can never grant access and a 401 ("authenticate and retry") would be a lie.
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // If no roles required, or S_EVERYONE is set, allow access without authentication
@@ -293,9 +294,9 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     ]);
     const roles = mergeRolesMetadata(reflectorRoles);
 
-    // Check if locked
+    // Check if locked — 403, never 401 (see canActivate: authenticating can never unlock it)
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Check roles

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -88,9 +88,11 @@ export class BetterAuthRolesGuard implements CanActivate {
     // Combine handler and class roles (handler takes precedence, like Reflector.getAll)
     const roles = mergeRolesMetadata([handlerRoles, classRoles]);
 
-    // Check if locked - always deny
+    // Check if locked - always deny. 403, never 401: the endpoint is locked permanently, so
+    // authenticating can never grant access and a 401 ("authenticate and retry") would be a lie.
+    // Kept in sync with RolesGuard (see .claude/rules/better-auth.md).
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // If no roles required, or S_EVERYONE is set, allow access without authentication

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import * as ejs from 'ejs';
+import ejs = require('ejs');
 import * as fs from 'fs';
 import * as path from 'path';
 

package/src/core/modules/better-auth/core-better-auth.controller.ts

@@ -5,6 +5,7 @@ import {
   Controller,
   Get,
   HttpCode,
+  HttpException,
   HttpStatus,
   InternalServerErrorException,
   Logger,
@@ -932,12 +933,10 @@ export class CoreBetterAuthController {
     } catch (error) {
       this.logger.error(`Better Auth handler error: ${error instanceof Error ? error.message : 'Unknown error'}`);
 
-      // Re-throw NestJS exceptions
-      if (
-        error instanceof BadRequestException ||
-        error instanceof UnauthorizedException ||
-        error instanceof InternalServerErrorException
-      ) {
+      // Re-throw NestJS exceptions. Matching HttpException (not an enumeration of subclasses) keeps
+      // any deliberately thrown status intact — an enumeration silently masks everything it forgets
+      // (e.g. a 403 from the rights checks) as a 500.
+      if (error instanceof HttpException) {
         throw error;
       }
 

package/src/core/modules/tenant/core-tenant-member.model.ts

@@ -1,10 +1,10 @@
-import { UnauthorizedException } from '@nestjs/common';
 import { ObjectType } from '@nestjs/graphql';
 import { Schema } from '@nestjs/mongoose';
 
 import { Restricted } from '../../common/decorators/restricted.decorator';
 import { UnifiedField } from '../../common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
 import { CorePersistenceModel } from '../../common/models/core-persistence.model';
 import { RequestContext } from '../../common/services/request-context.service';
 import { DefaultHR, TenantMemberStatus } from './core-tenant.enums';
@@ -98,7 +98,11 @@ export class CoreTenantMemberModel extends CorePersistenceModel {
    */
   override securityCheck(user: any, force?: boolean): this {
     if (force) return this;
-    if (!user) throw new UnauthorizedException('Access to tenant membership denied');
+    // accessDeniedException picks the status from the requester's auth state: 401 here (no user),
+    // 403 below (authenticated, but not owner / admin / tenant manager). Model-level denials must
+    // use this helper too — a permission error must never reach the client as a 401, or frontends
+    // treat it as an expired session and log the user out.
+    if (!user) throw accessDeniedException(user);
 
     // Own membership or system admin
     if (user.id === this.user || user.hasRole?.(RoleEnum.ADMIN)) return this;
@@ -116,6 +120,7 @@ export class CoreTenantMemberModel extends CorePersistenceModel {
       return this;
     }
 
-    throw new UnauthorizedException('Access to tenant membership denied');
+    // Reached only when `user` is set (the `!user` case returned above), so this is a 403.
+    throw accessDeniedException(user);
   }
 }

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -1,4 +1,12 @@
-import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+  Logger,
+  OnModuleDestroy,
+  UnauthorizedException,
+} from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
 import { InjectModel } from '@nestjs/mongoose';
@@ -6,6 +14,7 @@ import { Model } from 'mongoose';
 
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
+import { ErrorCode } from '../error-code/error-codes';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
 import { SKIP_TENANT_CHECK_KEY } from './core-tenant.decorators';
 import { TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums';
@@ -73,9 +82,14 @@ interface CachedTenantIds {
  * 5. @SkipTenantCheck → role check against user.roles, no tenant context
  * 6. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
  *
+ * Status codes (RFC 9110, aligned with RolesGuard since v11.28.0):
+ * - Missing authentication → 401 (re-authenticating IS the remedy, so the client must be told to)
+ * - Authenticated but lacking a right / membership → 403
+ * - S_NO_ONE → always 403 (authenticating can never unlock it)
+ *
  * HEADER PRESENT:
  *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
- *   - No user → 403 "Authentication required for tenant access"
+ *   - No user → 401 (tenant access requires authentication)
  *   - Authenticated non-admin user:
  *     - Active member → checkRoleAccess against membership.role → set req.tenantId + tenantRole
  *     - Not active member → ALWAYS 403
@@ -86,7 +100,7 @@ interface CachedTenantIds {
  *     → resolveUserTenantIds with minLevel filter
  *   - Authenticated + no checkable roles → resolveUserTenantIds (all memberships)
  *   - No user + no checkable roles → pass (plugin safety net catches tenantId-schema access)
- *   - No user + checkable roles → 403 "Authentication required"
+ *   - No user + checkable roles → 401 (authentication required)
  */
 @Injectable()
 export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
@@ -216,8 +230,9 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
 
     // Defense-in-depth: S_NO_ONE is normally caught by RolesGuard/BetterAuthRolesGuard upstream,
     // but guard it here too in case CoreTenantGuard runs standalone (e.g., custom guard chains).
+    // Always 403 — the same code the role guards return since v11.28.0.
     if (roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new ForbiddenException('Access denied');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     const sEveryoneGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_EVERYONE);
@@ -258,7 +273,7 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     const sUserGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_USER);
     if (sUserGrantsAccess) {
       if (!user) {
-        throw new ForbiddenException('Authentication required');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
       if (headerTenantId && !hasSkipDecorator) {
         return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
@@ -276,7 +291,7 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     const sVerifiedGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_VERIFIED);
     if (sVerifiedGrantsAccess) {
       if (!user) {
-        throw new ForbiddenException('Authentication required');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
       const isVerified = !!(user.verified || user.verifiedAt || user.emailVerified);
       if (!isVerified) {
@@ -337,9 +352,9 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
         return true;
       }
 
-      // No user + header → 403 (tenant access requires authentication)
+      // No user + header → 401 (tenant access requires authentication; re-auth is the remedy)
       if (!user) {
-        throw new ForbiddenException('Authentication required for tenant access');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
 
       // Authenticated non-admin user: MUST be active member
@@ -375,9 +390,9 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
 
     // Checkable roles present
     if (checkableRoles.length > 0) {
-      // No user + roles required → 403
+      // No user + roles required → 401 (re-auth is the remedy, so it must not be a 403)
       if (!user) {
-        throw new ForbiddenException('Authentication required');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
 
       // Check role access against user.roles (hierarchy: level comparison, normal: exact match)
@@ -604,7 +619,7 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     if (checkableRoles.length > 0) {
       // Defense-in-depth: reject unauthenticated access even if RolesGuard is absent
       if (!user) {
-        throw new ForbiddenException('Authentication required');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
       if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
         throw new ForbiddenException('Insufficient role');

package/src/index.ts

@@ -26,6 +26,7 @@ export * from './core/common/enums/logical-operator.enum';
 export * from './core/common/enums/process-type.enum';
 export * from './core/common/enums/role.enum';
 export * from './core/common/enums/sort-order.emum';
+export * from './core/common/exceptions/access-denied.exception';
 export * from './core/common/filters/http-exception-log.filter';
 export * from './core/common/helpers/common.helper';
 export * from './core/common/helpers/config.helper';

package/src/server/modules/user/user.service.ts

@@ -98,9 +98,10 @@ export class UserService extends CoreUserService<User, UserInput, UserCreateInpu
    */
   async setAvatar(file: Express.Multer.File, user: User): Promise<string> {
     const dbUser = await this.mainDbModel.findOne({ id: user.id }).exec();
-    // Check user
+    // Check user: the token is valid but the account no longer exists, so the session really is
+    // invalid — 401 is right here. (A permission error would have to be 403, see accessDeniedException.)
     if (!dbUser) {
-      throw new UnauthorizedException('User is not allowed to set the avatar');
+      throw new UnauthorizedException('User of the current session no longer exists');
     }
 
     // Check file