@lenne.tech/nest-server 11.27.6 → 11.28.0

package/src/core/modules/ai/services/core-ai-prompt.service.ts

@@ -10,8 +10,14 @@ import { CoreAiPromptCreateInput } from '../inputs/core-ai-prompt-create.input';
 import { CoreAiPromptUpdateInput } from '../inputs/core-ai-prompt-update.input';
 import { AiPromptDocument, CoreAiPrompt } from '../models/core-ai-prompt.model';
 
-export const AI_PROMPT_MODEL = 'AiPrompt';
-export const AI_PROMPT_CLASS = 'AI_PROMPT_CLASS';
+import { AI_PROMPT_CLASS, AI_PROMPT_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_PROMPT_CLASS, AI_PROMPT_MODEL } from '../core-ai.constants';
 
 const VALID_SCOPES = new Set(['tenant', 'user']);
 

package/src/core/modules/ai/services/core-ai-slot.service.ts

@@ -11,11 +11,14 @@ import { CoreAiSlotCreateInput } from '../inputs/core-ai-slot-create.input';
 import { CoreAiSlotUpdateInput } from '../inputs/core-ai-slot-update.input';
 import { AiSlotDocument, CoreAiSlot } from '../models/core-ai-slot.model';
 
-/** Mongoose injection token for the slot model. */
-export const AI_SLOT_MODEL = 'AiSlot';
+import { AI_SLOT_CLASS, AI_SLOT_MODEL } from '../core-ai.constants';
 
-/** DI token for the slot model constructor. */
-export const AI_SLOT_CLASS = 'AI_SLOT_CLASS';
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_SLOT_CLASS, AI_SLOT_MODEL } from '../core-ai.constants';
 
 /** A resolved prompt fragment ready for placeholder rendering + assembly. */
 export interface ResolvedPromptFragment {

package/src/core/modules/ai/services/core-ai-tool-grant.service.ts

@@ -6,10 +6,14 @@ import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiToolGrantDocument, CoreAiToolGrant } from '../models/core-ai-tool-grant.model';
 
-/** Mongoose injection token. */
-export const AI_TOOL_GRANT_MODEL = 'AiToolGrant';
-/** DI token for the model constructor. */
-export const AI_TOOL_GRANT_CLASS = 'AI_TOOL_GRANT_CLASS';
+import { AI_TOOL_GRANT_CLASS, AI_TOOL_GRANT_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_TOOL_GRANT_CLASS, AI_TOOL_GRANT_MODEL } from '../core-ai.constants';
 
 /** Scope of a persisted permission decision. */
 export type AiToolGrantScope = 'conversation' | 'tenant' | 'user';

package/src/core/modules/ai/services/core-ai-tool-policy.service.ts

@@ -6,10 +6,14 @@ import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiToolPolicyDocument, CoreAiToolPolicy } from '../models/core-ai-tool-policy.model';
 
-/** Mongoose injection token. */
-export const AI_TOOL_POLICY_MODEL = 'AiToolPolicy';
-/** DI token for the model constructor. */
-export const AI_TOOL_POLICY_CLASS = 'AI_TOOL_POLICY_CLASS';
+import { AI_TOOL_POLICY_CLASS, AI_TOOL_POLICY_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_TOOL_POLICY_CLASS, AI_TOOL_POLICY_MODEL } from '../core-ai.constants';
 
 export interface AiToolPolicyDecision {
   /** Final decision: 'allow', 'deny' or 'ask'. */

package/src/core/modules/ai/services/core-ai.service.ts

@@ -27,20 +27,17 @@ import { AiPromptFeedbackSignal, CoreAiPromptHintService } from './core-ai-promp
 import { AiToolGrantScope, CoreAiToolGrantService } from './core-ai-tool-grant.service';
 import { CoreAiToolPolicyService } from './core-ai-tool-policy.service';
 import { CoreAiModeService } from './core-ai-mode.service';
+import type { AiInteractionRecord } from '../interfaces/ai-interaction-record.interface';
 
 /**
- * Record passed to {@link CoreAiService.audit} for each prompt run.
+ * @deprecated Import from `../interfaces/ai-interaction-record.interface` instead. Re-exported only
+ * so existing imports keep working.
+ *
+ * The type was moved out of this file because `core-ai-interaction.service` needs it while this file
+ * imports THAT service — an import cycle held apart only by an `import type`. See the interface's
+ * docblock.
  */
-export interface AiInteractionRecord {
-  actions: { name: string; success: boolean }[];
-  connectionId: string;
-  iterations: number;
-  prompt: string;
-  responseText: string;
-  tenantId?: string;
-  usage?: { completionTokens?: number; promptTokens?: number; totalTokens?: number };
-  userId?: string;
-}
+export type { AiInteractionRecord } from '../interfaces/ai-interaction-record.interface';
 
 /**
  * Event emitted by {@link CoreAiService.promptStream} over SSE.

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

@@ -13,7 +13,7 @@ import { ErrorCode } from '../error-code';
 import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthenticatedUser } from './better-auth.types';
-import { CoreBetterAuthModule } from './core-better-auth.module';
+import { getBetterAuthTokenService } from './core-better-auth.registry';
 
 /**
  * BetterAuth Roles Guard
@@ -33,7 +33,8 @@ import { CoreBetterAuthModule } from './core-better-auth.module';
  * IMPORTANT: This guard has NO constructor dependencies. This is intentional because
  * NestJS DI has issues resolving Reflector/ModuleRef for APP_GUARD providers in dynamic modules.
  * Instead, we use Reflect.getMetadata directly to read decorator metadata, and access
- * BetterAuthTokenService via CoreBetterAuthModule static reference.
+ * BetterAuthTokenService via the core-better-auth.registry leaf module — NOT via
+ * CoreBetterAuthModule, which would make guard and module import each other.
  */
 @Injectable()
 export class BetterAuthRolesGuard implements CanActivate {
@@ -41,12 +42,17 @@ export class BetterAuthRolesGuard implements CanActivate {
   private tokenService: BetterAuthTokenService | null = null;
 
   /**
-   * Get BetterAuthTokenService lazily from CoreBetterAuthModule
-   * This avoids DI issues while still allowing token verification
+   * Get BetterAuthTokenService lazily from the better-auth registry.
+   * This avoids DI issues while still allowing token verification.
+   *
+   * The lookup goes through core-better-auth.registry.ts rather than
+   * CoreBetterAuthModule on purpose: importing the module here would make guard
+   * and module import each other, and that cycle is one decorator away from the
+   * SWC temporal-dead-zone crash documented in core-better-auth.constants.ts.
    */
   private getTokenService(): BetterAuthTokenService | null {
     if (!this.tokenService) {
-      this.tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+      this.tokenService = getBetterAuthTokenService();
     }
     return this.tokenService;
   }
@@ -82,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/better-auth.config.ts

@@ -476,6 +476,22 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
       finalConfig.advanced = {
         ...(betterAuthConfig.advanced as Record<string, unknown>),
         ...(optionsAdvanced as Record<string, unknown>),
+        // `defaultCookieAttributes` needs a DEEP merge, not the shallow spread above.
+        // It is the key that carries our restored `secure: true` (see the `useSecureCookies: false`
+        // block), so a consumer setting it for an entirely unrelated reason — `{ partitioned: true }`,
+        // `{ domain: … }` — would wholesale-replace the object and silently strip `Secure` from every
+        // session cookie the native handlers forward (2FA verify, social callback, magic link) on an
+        // https deployment. Session-establishing cookies, in the clear, with no error anywhere.
+        // Re-apply `secure: true` as the BASE and let the consumer's keys spread over it, so an
+        // EXPLICIT `secure: false` still wins while an unrelated key can no longer clobber it.
+        ...(secureCookies && {
+          defaultCookieAttributes: {
+            secure: true,
+            ...((optionsAdvanced as Record<string, unknown>).defaultCookieAttributes as
+              | Record<string, unknown>
+              | undefined),
+          },
+        }),
       };
     }
   } else {

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

@@ -0,0 +1,73 @@
+/**
+ * Dependency-injection tokens of the better-auth module.
+ *
+ * These live in a dedicated file — instead of core-better-auth.module.ts /
+ * core-better-auth.service.ts — so that module and service never have to import
+ * each other. The tokens used to be split across both files
+ * (BETTER_AUTH_INSTANCE in the module, BETTER_AUTH_CONFIG /
+ * BETTER_AUTH_COOKIE_DOMAIN in the service), which made the two files import
+ * each other in a cycle. That cycle happened to work under tsc/CommonJS by
+ * evaluation-order luck, but crashed SWC-compiled builds (`nest start -b swc`)
+ * with a temporal-dead-zone error:
+ *
+ *   ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+ *
+ * The lethal ingredient is not the cycle by itself — it is a cycle PLUS a read of
+ * the cyclic binding at module-evaluation time. `@Inject(BETTER_AUTH_INSTANCE)` is
+ * a constructor-parameter decorator, and decorator arguments are evaluated when the
+ * class is defined, i.e. while the module is still initializing. On a cycle the
+ * importing side then reads a `const` that has not been initialized yet.
+ *
+ * This file imports nothing, so it can never be mid-evaluation when someone
+ * imports it — in any module system, under any compiler. That makes the
+ * initialization order of the tokens deterministic everywhere.
+ *
+ * WHY THIS MATTERS FOR FUTURE CHANGES
+ * -----------------------------------
+ * `tsc` does NOT catch a regression here, and neither does the test suite: vitest
+ * runs SWC through Vite's module runner, whose getter-based live bindings tolerate
+ * cycles. Only the SWC → CommonJS → `require()` path fails, which is exactly what
+ * `pnpm run check:swc-tdz` exercises. If you move a token back into the module or
+ * the service, everything stays green locally and breaks for consumers.
+ *
+ * The rule, in short: **DI tokens belong in an import-free leaf file.**
+ * See .claude/rules/better-auth.md §6.
+ */
+
+/**
+ * Token for injecting the better-auth instance.
+ *
+ * Injected type: `BetterAuthInstance | null` — null when better-auth is disabled.
+ * Declared `@Optional()` in the CoreBetterAuthService constructor.
+ *
+ * @example
+ * ```typescript
+ * import { Inject, Injectable, Optional } from '@nestjs/common';
+ * import { BETTER_AUTH_INSTANCE, BetterAuthInstance } from '@lenne.tech/nest-server';
+ *
+ * @Injectable()
+ * export class MyService {
+ *   constructor(
+ *     @Optional() @Inject(BETTER_AUTH_INSTANCE) private readonly auth: BetterAuthInstance | null,
+ *   ) {}
+ * }
+ * ```
+ */
+export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
+
+/**
+ * Injection token for the resolved BetterAuth configuration.
+ *
+ * Injected type: `IBetterAuth | null` — null when better-auth is disabled.
+ * Declared `@Optional()` in the CoreBetterAuthService constructor.
+ */
+export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
+
+/**
+ * Injection token for the resolved cross-subdomain cookie domain.
+ * Set during Better-Auth instance creation, undefined if disabled.
+ *
+ * Injected type: `string | null | undefined`.
+ * Declared `@Optional()` in the CoreBetterAuthService constructor.
+ */
+export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';

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/better-auth/core-better-auth.module.ts

@@ -28,15 +28,34 @@ import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit
 import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service';
 import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 import { CoreBetterAuthController } from './core-better-auth.controller';
 import { CoreBetterAuthMiddleware } from './core-better-auth.middleware';
+import {
+  getBetterAuthTokenService,
+  resetBetterAuthRegistry,
+  setBetterAuthTokenService,
+} from './core-better-auth.registry';
 import { CoreBetterAuthResolver } from './core-better-auth.resolver';
-import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, CoreBetterAuthService } from './core-better-auth.service';
+import { CoreBetterAuthService } from './core-better-auth.service';
 
 /**
- * Token for injecting the better-auth instance
+ * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
+ * so existing deep imports keep working; it will be dropped in a future MINOR.
+ *
+ * Do NOT import this token from here inside the better-auth module itself — the
+ * token must come from the constants leaf, or module and service start importing
+ * each other again and SWC builds crash with a temporal-dead-zone ReferenceError
+ * (see core-better-auth.constants.ts).
+ *
+ * NOTE: the `@deprecated` tag above is documentation only — TypeScript does not
+ * honor JSDoc on an `export … from` declaration. Do NOT try to "fix" that by
+ * re-declaring the token as a local `const`: that would give the barrel two
+ * distinct declarations of the same name and turn its `export *` into a TS2308
+ * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
+ * `tests/unit/better-auth-di-tokens.spec.ts`.
  */
-export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
+export { BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 
 /**
  * Options for CoreBetterAuthModule.forRoot()
@@ -239,10 +258,11 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   // Safety Net: Track if forRoot() has already been called to detect duplicate registration
   private static forRootCalled = false;
   private static cachedDynamicModule: DynamicModule | null = null;
-  // Static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+  // Static references for lazy GraphQL driver (autoRegister: false).
+  // The BetterAuthTokenService reference lives in core-better-auth.registry.ts instead,
+  // so BetterAuthRolesGuard can read it without importing this module (cycle-free).
   private static serviceInstance: CoreBetterAuthService | null = null;
   private static userMapperInstance: CoreBetterAuthUserMapper | null = null;
-  private static tokenServiceInstance: BetterAuthTokenService | null = null;
   private static resolvedCookieDomain: string | undefined = undefined;
 
   /**
@@ -279,11 +299,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
   /**
    * Gets the static BetterAuthTokenService instance.
-   * Used by BetterAuthRolesGuard for token verification when user isn't already on request.
    * Safe because guards are invoked only after module initialization.
+   *
+   * Delegates to the core-better-auth.registry leaf module, which is the single
+   * source of truth. BetterAuthRolesGuard reads the registry directly instead of
+   * calling this method, so that guard and module never import each other.
    */
   static getTokenServiceInstance(): BetterAuthTokenService | null {
-    return this.tokenServiceInstance;
+    return getBetterAuthTokenService();
   }
 
   /**
@@ -315,7 +338,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       CoreBetterAuthModule.userMapperInstance = this.userMapper;
     }
     if (this.tokenService) {
-      CoreBetterAuthModule.tokenServiceInstance = this.tokenService;
+      setBetterAuthTokenService(this.tokenService);
     }
 
     // Configure rate limiter with stored config
@@ -747,6 +770,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.serviceInstance = null;
     this.userMapperInstance = null;
     this.resolvedCookieDomain = undefined;
+    // Reset the BetterAuthTokenService reference used by BetterAuthRolesGuard.
+    // Without this a token service from a previous testing module leaks into the next one.
+    resetBetterAuthRegistry();
     // Reset shared RolesGuard registry (shared with CoreAuthModule)
     RolesGuardRegistry.reset();
   }

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

@@ -0,0 +1,53 @@
+/**
+ * Runtime registry for better-auth singletons that must be reachable from files
+ * which cannot import core-better-auth.module.ts.
+ *
+ * `BetterAuthRolesGuard` deliberately has no constructor dependencies (see
+ * .claude/rules/better-auth.md §5), so it cannot receive `BetterAuthTokenService`
+ * through DI and has to look it up statically. Reading it from
+ * `CoreBetterAuthModule` would make guard and module import each other — the same
+ * cycle shape that crashed SWC builds when the DI tokens still lived in the module
+ * and the service (see core-better-auth.constants.ts).
+ *
+ * This file therefore holds the reference instead. It uses only `import type`,
+ * which both tsc and SWC erase entirely, so it emits no `require()` at all and is
+ * a true leaf: it can never be mid-evaluation when someone imports it, in any
+ * module system, under any compiler.
+ *
+ * @internal Populated by CoreBetterAuthModule.onModuleInit(). Read it through the
+ * public `CoreBetterAuthModule.getTokenServiceInstance()` unless you are in a file
+ * that the module itself imports — importing the module from there would re-create
+ * the cycle.
+ */
+
+import type { BetterAuthTokenService } from './better-auth-token.service';
+
+let tokenServiceInstance: BetterAuthTokenService | null = null;
+
+/**
+ * Stores the BetterAuthTokenService singleton.
+ * Called by CoreBetterAuthModule during module initialization.
+ * @internal
+ */
+export function setBetterAuthTokenService(service: BetterAuthTokenService | null): void {
+  tokenServiceInstance = service;
+}
+
+/**
+ * Returns the BetterAuthTokenService singleton, or null when better-auth is
+ * disabled or the module has not initialized yet.
+ *
+ * Safe to call from guards: they run only after module initialization.
+ */
+export function getBetterAuthTokenService(): BetterAuthTokenService | null {
+  return tokenServiceInstance;
+}
+
+/**
+ * Clears the registry. Called by CoreBetterAuthModule.reset() so tests do not
+ * leak a token service from a previous testing module into the next one.
+ * @internal
+ */
+export function resetBetterAuthRegistry(): void {
+  tokenServiceInstance = null;
+}

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

@@ -13,7 +13,7 @@ import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helpe
 import { BetterAuthInstance } from './better-auth.config';
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper';
-import { BETTER_AUTH_INSTANCE } from './core-better-auth.module';
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
 
 /**
  * Result of a session validation
@@ -28,6 +28,24 @@ export interface SessionResult {
   user: BetterAuthSessionUser | null;
 }
 
+/**
+ * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
+ * so existing deep imports keep working; it will be dropped in a future MINOR.
+ *
+ * Do NOT import these tokens from here inside the better-auth module itself — they
+ * must come from the constants leaf, or module and service start importing each
+ * other again and SWC builds crash with a temporal-dead-zone ReferenceError
+ * (see core-better-auth.constants.ts).
+ *
+ * NOTE: the `@deprecated` tag above is documentation only — TypeScript does not
+ * honor JSDoc on an `export … from` declaration. Do NOT try to "fix" that by
+ * re-declaring the tokens as local `const`s: that would give the barrel two
+ * distinct declarations of the same name and turn its `export *` into a TS2308
+ * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
+ * `tests/unit/better-auth-di-tokens.spec.ts`.
+ */
+export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-auth.constants';
+
 /**
  * CoreBetterAuthService provides a NestJS-friendly wrapper around the better-auth instance.
  *
@@ -51,17 +69,6 @@ export interface SessionResult {
  * }
  * ```
  */
-/**
- * Injection token for resolved BetterAuth configuration
- */
-export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
-
-/**
- * Injection token for resolved cross-subdomain cookie domain.
- * Set during Better-Auth instance creation, undefined if disabled.
- */
-export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
-
 @Injectable()
 export class CoreBetterAuthService implements OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);

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

@@ -39,8 +39,17 @@ export * from './core-better-auth-signup-validator.service';
 export * from './core-better-auth-token.helper';
 export * from './core-better-auth-user.mapper';
 export * from './core-better-auth-web.helper';
+export * from './core-better-auth.constants';
 export * from './core-better-auth.controller';
 export * from './core-better-auth.middleware';
 export * from './core-better-auth.module';
+// NOT exported: './core-better-auth.registry'.
+//
+// It is module-internal plumbing that only exists so BetterAuthRolesGuard can reach
+// BetterAuthTokenService without importing CoreBetterAuthModule (see .claude/rules/better-auth.md
+// §6). Re-exporting it would put `setBetterAuthTokenService()` on the public API — letting a
+// consumer swap or null the very token service the guard makes its authorization decisions with.
+// Consumers that need the instance already have the public, read-only
+// `CoreBetterAuthModule.getTokenServiceInstance()`.
 export * from './core-better-auth.resolver';
 export * from './core-better-auth.service';

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);
   }
 }