@lenne.tech/nest-server 11.27.7 → 11.28.0

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.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