@lenne.tech/nest-server 11.27.6 → 11.27.7

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.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/tus/tus.constants.ts

@@ -0,0 +1,25 @@
+/**
+ * Dependency-injection tokens of the TUS module.
+ *
+ * They live in a dedicated, import-free leaf file — never in `tus.module.ts` or a service — so that
+ * no file needing a token has to import the module (or vice versa) and close an import cycle.
+ *
+ * On a cycle, a token read at MODULE-EVALUATION time — inside an `@Inject()` decorator argument, in
+ * `design:paramtypes` metadata, or in a static field initializer — reads a `const` still in its
+ * temporal dead zone, and SWC-compiled builds (`nest start -b swc`) die at startup with:
+ *
+ *   ReferenceError: Cannot access 'TUS_CONFIG' before initialization
+ *
+ * A file that imports nothing can never be mid-evaluation when someone imports it, in any module
+ * system, under any compiler. That is the whole point — keep it import-free.
+ *
+ * `tsc`, `pnpm test` and `oxlint` are all blind to a regression here; only `pnpm run check:swc-tdz`
+ * sees it. See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * Token for injecting the resolved TUS configuration.
+ *
+ * Injected type: `Required<ITusConfig>`.
+ */
+export const TUS_CONFIG = 'TUS_CONFIG';

package/src/core/modules/tus/tus.module.ts

@@ -5,12 +5,17 @@ import { Connection } from 'mongoose';
 import { ITusConfig } from '../../common/interfaces/server-options.interface';
 import { CoreTusController } from './core-tus.controller';
 import { CoreTusService } from './core-tus.service';
+import { TUS_CONFIG } from './tus.constants';
 import { normalizeTusConfig } from './interfaces/tus-config.interface';
 
 /**
- * Token for injecting the TUS configuration
+ * @deprecated Import from `./tus.constants` instead. Re-exported only so existing deep imports keep
+ * working; the token is declared in an import-free leaf so module and services stay acyclic
+ * (SWC-safe — see tus.constants.ts).
+ *
+ * Do NOT import it from here inside the TUS module itself — that is what re-creates the cycle.
  */
-export const TUS_CONFIG = 'TUS_CONFIG';
+export { TUS_CONFIG } from './tus.constants';
 
 /**
  * Options for TusModule.forRoot()