@lenne.tech/nest-server 11.27.5 → 11.27.7

package/src/core/modules/ai/index.ts

@@ -20,6 +20,7 @@ export * from './inputs/core-ai-slot-update.input';
 export * from './inputs/core-ai-prompt.input';
 export * from './hooks/ai-hook.base';
 export * from './hooks/ai-hook.registry';
+export * from './interfaces/ai-interaction-record.interface';
 export * from './interfaces/ai-hook.interface';
 export * from './interfaces/ai-placeholder.interface';
 export * from './interfaces/ai-tool.interface';

package/src/core/modules/ai/interfaces/ai-interaction-record.interface.ts

@@ -0,0 +1,34 @@
+/**
+ * The record passed to `CoreAiService.audit()` for each prompt run.
+ *
+ * It lives here, in an import-free leaf, rather than in `core-ai.service.ts` — and that is
+ * load-bearing, not tidiness.
+ *
+ * `core-ai.service` imports `core-ai-interaction.service` (it needs the class), and
+ * `core-ai-interaction.service` needs this type back. Declared in the service, that pair forms an
+ * import cycle. It never crashed for exactly one reason: the type was pulled in with `import type`,
+ * which both tsc and SWC erase, so no `require()` was emitted and the cycle was never real at
+ * runtime.
+ *
+ * That is a single keyword of protection, on a file where `core-ai.service` has a constructor
+ * `@Inject`, so `emitDecoratorMetadata` emits `design:paramtypes` at module-evaluation time — the
+ * exact eval-time dereference that turns a cycle fatal. An IDE "organize imports" or a lint autofix
+ * widening `import type` to a plain `import` would have armed it silently, and `tsc`, `pnpm test`
+ * and `oxlint` are ALL blind to that (vitest runs SWC through Vite's cycle-tolerant module runner).
+ * Only `pnpm run check:swc-tdz` would have caught it — after the fact.
+ *
+ * Moving the type out removes the edge entirely, so the cycle no longer exists rather than merely
+ * being disarmed. `core-ai.service` re-exports it, so every existing import path still resolves.
+ *
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+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;
+}

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

@@ -11,10 +11,14 @@ import { CoreAiBudgetLimitInput } from '../inputs/core-ai-budget-limit.input';
 import { AiBudgetLimitDocument, CoreAiBudgetLimit } from '../models/core-ai-budget-limit.model';
 import { CoreAiBudgetSummary, CoreAiUsageInfo, CoreAiUsageScope } from '../models/core-ai-usage-info.model';
 
-/** Mongoose injection token for the budget-limit model. */
-export const AI_BUDGET_LIMIT_MODEL = 'AiBudgetLimit';
-/** DI token for the budget-limit model constructor. */
-export const AI_BUDGET_LIMIT_CLASS = 'AI_BUDGET_LIMIT_CLASS';
+import { AI_BUDGET_LIMIT_CLASS, AI_BUDGET_LIMIT_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_BUDGET_LIMIT_CLASS, AI_BUDGET_LIMIT_MODEL } from '../core-ai.constants';
 
 /** Resolved effective limit for a scope. */
 export interface ResolvedAiBudgetLimit {

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

@@ -10,10 +10,14 @@ import {
   CoreAiConnectionPreference,
 } from '../models/core-ai-connection-preference.model';
 
-/** Mongoose injection token for the connection-preference model. */
-export const AI_CONNECTION_PREFERENCE_MODEL = 'AiConnectionPreference';
-/** DI token for the connection-preference model constructor. */
-export const AI_CONNECTION_PREFERENCE_CLASS = 'AI_CONNECTION_PREFERENCE_CLASS';
+import { AI_CONNECTION_PREFERENCE_CLASS, AI_CONNECTION_PREFERENCE_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_CONNECTION_PREFERENCE_CLASS, AI_CONNECTION_PREFERENCE_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD + lookup for {@link CoreAiConnectionPreference} (tenant/user connection

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

@@ -23,15 +23,14 @@ import { LlmProviderFactory } from '../providers/llm-provider.factory';
 import { AiCryptoService } from './ai-crypto.service';
 import { CoreAiConnectionPreferenceService } from './core-ai-connection-preference.service';
 
-/**
- * Mongoose injection token for the AI connection model.
- */
-export const AI_CONNECTION_MODEL = 'AiConnection';
+import { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI connection model constructor (used by CrudService mapping).
+ * @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 const AI_CONNECTION_CLASS = 'AI_CONNECTION_CLASS';
+export { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD service for {@link CoreAiConnection} — the database-backed LLM

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

@@ -8,15 +8,14 @@ import { CoreAiConversationCreateInput } from '../inputs/core-ai-conversation-cr
 import { CoreAiConversationInput } from '../inputs/core-ai-conversation.input';
 import { AiConversationDocument, CoreAiConversation } from '../models/core-ai-conversation.model';
 
-/**
- * Mongoose injection token for the AI conversation model.
- */
-export const AI_CONVERSATION_MODEL = 'AiConversation';
+import { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI conversation model constructor.
+ * @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 const AI_CONVERSATION_CLASS = 'AI_CONVERSATION_CLASS';
+export { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD service for multi-turn {@link CoreAiConversation}s.

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

@@ -5,17 +5,16 @@ import { Model } from 'mongoose';
 import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiInteractionDocument, CoreAiInteraction } from '../models/core-ai-interaction.model';
-import type { AiInteractionRecord } from './core-ai.service';
+import type { AiInteractionRecord } from '../interfaces/ai-interaction-record.interface';
 
-/**
- * Mongoose injection token for the AI interaction model.
- */
-export const AI_INTERACTION_MODEL = 'AiInteraction';
+import { AI_INTERACTION_CLASS, AI_INTERACTION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI interaction model constructor.
+ * @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 const AI_INTERACTION_CLASS = 'AI_INTERACTION_CLASS';
+export { AI_INTERACTION_CLASS, AI_INTERACTION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD + write service for {@link CoreAiInteraction} audit records.

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

@@ -6,8 +6,14 @@ import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiModeDocument, CoreAiMode } from '../models/core-ai-mode.model';
 
-export const AI_MODE_MODEL = 'AiMode';
-export const AI_MODE_CLASS = 'AI_MODE_CLASS';
+import { AI_MODE_CLASS, AI_MODE_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_MODE_CLASS, AI_MODE_MODEL } from '../core-ai.constants';
 
 /**
  * Named-mode store. See {@link CoreAiMode}. Override via

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

@@ -9,11 +9,14 @@ import { CoreAiPromptHintCreateInput } from '../inputs/core-ai-prompt-hint-creat
 import { CoreAiPromptHintInput } from '../inputs/core-ai-prompt-hint.input';
 import { AiPromptHintDocument, CoreAiPromptHint } from '../models/core-ai-prompt-hint.model';
 
-/** Mongoose injection token for the prompt-hint model. */
-export const AI_PROMPT_HINT_MODEL = 'AiPromptHint';
+import { AI_PROMPT_HINT_CLASS, AI_PROMPT_HINT_MODEL } from '../core-ai.constants';
 
-/** DI token for the prompt-hint model constructor. */
-export const AI_PROMPT_HINT_CLASS = 'AI_PROMPT_HINT_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_PROMPT_HINT_CLASS, AI_PROMPT_HINT_MODEL } from '../core-ai.constants';
 
 /** A failure signal recorded by the orchestrator for the learning loop. */
 export interface AiPromptFeedbackSignal {

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/better-auth/README.md

@@ -262,10 +262,10 @@ Read the security section below for production deployments.
 
 **Global server-level settings that affect BetterAuth behavior (since v11.25.0):**
 
-| Setting (top-level `IServerOptions`)                                          | Technical Purpose                                                                                                                                                                      | Impact of Wrong Value                                                                                                         |
-| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `cookies` (`boolean \| ICookiesConfig`, default: `true`)                      | Controls cookie-parser middleware and session cookie setting. `cookies.exposeTokenInBody` additionally returns the token in the response body (test-only; **forbidden in production**) | Tokens missing from response body surprises test clients; `exposeTokenInBody` in prod = XSS-risk, framework throws at startup |
-| `cors` (`boolean \| ICorsConfig`, default: enabled with auto-derived origins) | Unified CORS config — propagates to GraphQL (Apollo), REST (Express), and BetterAuth `trustedOrigins` from a single source                                                             | `cors.enabled: false` disables all three layers; `cors.allowAll` allows any origin (dev only)                                 |
+| Setting (top-level `IServerOptions`)                                          | Technical Purpose                                                                                                                                                                      | Impact of Wrong Value                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cookies` (`boolean \| ICookiesConfig`, default: `true`)                      | Controls cookie-parser middleware and session cookie setting. `cookies.exposeTokenInBody` additionally returns the token in the response body (test-only; **forbidden in production**) | Tokens missing from response body surprises test clients; `exposeTokenInBody` in prod = XSS-risk, framework throws at startup                                                                                          |
+| `cors` (`boolean \| ICorsConfig`, default: enabled with auto-derived origins) | Unified CORS config — propagates to GraphQL (Apollo), REST (Express), and BetterAuth `trustedOrigins` from a single source                                                             | `cors.enabled: false` disables the REST/GraphQL layers; `cors.allowAll` mirrors any request origin for REST/GraphQL (dev only) but BetterAuth keeps restricting to `appUrl` (its origin check has no "allow all" mode) |
 
 **For Development:** The defaults (`http://localhost:3000`, `/iam`) are correct.
 
@@ -725,6 +725,12 @@ const config = {
       },
       advanced: {
         cookiePrefix: 'my-app',
+        // Since v11.27.6 the framework pins `useSecureCookies: false` so Better-Auth's native
+        // handlers read the same UNPREFIXED cookie the nest-server helper writes (the `Secure`
+        // attribute is still applied on https via `advanced.defaultCookieAttributes`). Only set
+        // `true` if Better-Auth manages your cookies entirely — otherwise its native handlers
+        // look for a `__Secure-`-prefixed cookie that is never written and answer 401 on
+        // 2FA / passkey / `/token`.
         useSecureCookies: true,
       },
     },

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

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

@@ -7,7 +7,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { resolveServerUrls } from '../../common/helpers/cookies.helper';
+import { resolveServerUrls, strippedApiHostname } from '../../common/helpers/cookies.helper';
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 
@@ -380,15 +380,47 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     );
   }
 
+  // Better-Auth base URL (resolved localhost defaults → explicit config → fallback).
+  const betterAuthBaseUrl = resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000';
+  // The `Secure` attribute Better-Auth WOULD derive for its cookies if `useSecureCookies`
+  // were not pinned below: an `https://` baseURL is Better-Auth's own signal
+  // (createCookieGetter → `baseURLString.startsWith('https://')`). We keep exactly this value so
+  // the pinned `useSecureCookies: false` (needed for name alignment, see below) does not silently
+  // strip `Secure` from the cookies Better-Auth's native handlers forward.
+  const secureCookies = betterAuthBaseUrl.startsWith('https://');
+
   const betterAuthConfig: Record<string, unknown> = {
     advanced: {
       cookiePrefix,
       ...(crossSubDomain.enabled && {
         crossSubDomainCookies: { domain: crossSubDomain.domain, enabled: true },
       }),
+      // Keep Better-Auth's NATIVE handlers on the SAME cookie name the
+      // nest-server cookie helpers actually write. Those helpers always emit
+      // the UNPREFIXED `<cookiePrefix>.session_token`. Better-Auth, left to its
+      // own devices on an `https://` baseURL, auto-enables secure cookies AND
+      // prefixes the name with `__Secure-`, so its native handlers (2FA
+      // enable/disable, passkey register/list, backup codes, `/token`) look for
+      // `__Secure-<cookiePrefix>.session_token` — a cookie that is never written
+      // — and return `401 UNAUTHORIZED`, while the project's own session
+      // resolver (which reads the unprefixed cookie) still returns a session: a
+      // split-brain where `GET /iam/get-session` is 200 but every sensitive
+      // Better-Auth endpoint is 401. Pinning `useSecureCookies: false` keeps the
+      // native read path aligned with the cookie helper.
+      useSecureCookies: false,
+      // …BUT `useSecureCookies: false` also forces `secure: false` on EVERY cookie
+      // Better-Auth sets (createCookieGetter → `secure: !!secureCookiePrefix`), and the
+      // native handlers forward their `Set-Cookie` VERBATIM via `sendWebResponse`
+      // (2FA verify, social callback, magic link, passkey) WITHOUT passing through the
+      // cookie helper — so those session cookies would ship without `Secure` in
+      // production. Restore the exact Secure flag Better-Auth itself would have derived
+      // (an `https://` baseURL), keeping the unprefixed NAME while preserving the
+      // `Secure` TRANSPORT flag. Only injected on https so http/local and a consumer's
+      // own `options.advanced.useSecureCookies` override are left untouched.
+      ...(secureCookies && { defaultCookieAttributes: { secure: true } }),
     },
     basePath,
-    baseURL: resolvedUrls.baseUrl || config.baseUrl || 'http://localhost:3000',
+    baseURL: betterAuthBaseUrl,
     database: mongodbAdapter(db),
     // Enable email/password authentication by default (required by Better-Auth 1.x)
     // Can be disabled by setting config.emailAndPassword.enabled = false
@@ -444,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 {
@@ -681,12 +729,20 @@ function buildSocialProviders(config: IBetterAuth): Record<string, SocialProvide
  *
  * Behavior (in priority order):
  * 1. Explicit betterAuth.trustedOrigins → use those (always takes precedence)
- * 2. Server CORS disabled → empty array (BetterAuth CORS also disabled)
- * 3. Server CORS allowAll → undefined (BetterAuth allows all origins)
+ * 2. Server CORS disabled → empty array (adds no extra trusted origins beyond BetterAuth's own
+ *    baseURL — see NOTE; it does NOT switch BetterAuth's origin check off)
+ * 3. Server CORS allowAll → fall through to rules 4-7 (see below)
  * 4. Server CORS allowedOrigins → merge with appUrl/baseUrl
  * 5. Passkey trustedOrigins → use from normalizePasskeyConfig()
  * 6. Fallback to resolved appUrl
- * 7. Otherwise → undefined (allows all origins via Better-Auth's default)
+ * 7. Otherwise → undefined (Better-Auth then trusts only its own baseURL)
+ *
+ * NOTE on rules 2 and 7: neither an empty array (rule 2) nor `undefined` (rule 7) means "any
+ * origin is allowed", and neither disables BetterAuth's origin check. In both cases BetterAuth
+ * still derives and trusts its own `baseURL` origin (see `getTrustedOrigins()` in
+ * `better-auth/context`, which unconditionally pushes `new URL(baseURL).origin` before appending
+ * `options.trustedOrigins`), so `[]` and `undefined` are behaviorally identical here: a
+ * separately hosted frontend is still rejected by every origin-checked endpoint.
  *
  * @param config - Better-auth configuration
  * @param options - Passkey normalization, resolved URLs, and server CORS context
@@ -706,15 +762,25 @@ export function buildTrustedOrigins(
     return config.trustedOrigins;
   }
 
-  // 2. Server CORS disabled → BetterAuth CORS also disabled
+  // 2. Server CORS disabled → add no extra trusted origins. BetterAuth still trusts its own
+  //    baseURL (see the NOTE above), so this does NOT turn its origin check off — it only means
+  //    "no separately hosted frontend is trusted". Behaviorally identical to rule 7's undefined.
   if (serverCorsConfig === false || (typeof serverCorsConfig === 'object' && serverCorsConfig?.enabled === false)) {
     return [];
   }
 
-  // 3. Server CORS allowAll → BetterAuth allows all origins
-  if (typeof serverCorsConfig === 'object' && serverCorsConfig?.allowAll) {
-    return undefined;
-  }
+  // 3. Server CORS allowAll → fall through to the appUrl / passkey rules below.
+  //
+  // This used to `return undefined` in the belief that BetterAuth then "allows all
+  // origins". It does not: without trustedOrigins BetterAuth trusts only its own
+  // baseURL, so the *app* origin is rejected and every origin-checked endpoint
+  // (two-factor/enable, passkey) answers 403 INVALID_ORIGIN. That silently broke
+  // 2FA and passkeys in exactly the setups that use allowAll — local dev and CI.
+  //
+  // An origin check has no meaningful "allow everything" mode — that is the very
+  // thing it defends against — so allowAll now yields the known-good origins
+  // (appUrl, passkey) instead of none. Projects that really do want to accept
+  // arbitrary origins can still set `betterAuth.trustedOrigins` explicitly (rule 1).
 
   // 4. Server allowedOrigins → merge with appUrl/baseUrl.
   // Order (appUrl, baseUrl, allowedOrigins) mirrors buildCorsConfig() in cookies.helper.ts
@@ -1183,6 +1249,17 @@ export function resolveCrossSubDomainCookies(
  * 3. Use baseUrl hostname as-is
  *
  * Returns undefined for localhost (cross-subdomain not meaningful there).
+ *
+ * The `api.` strip reuses {@link strippedApiHostname} so it shares that helper's guard against
+ * bogus results: `api.dev` → `dev` would set a public-suffix cookie domain that browsers reject
+ * outright (dropping every session cookie), so `api.dev` is kept as-is instead.
+ *
+ * KNOWN LIMITATION (fails closed, no leak): the single-label guard cannot recognise a MULTI-label
+ * public suffix — `api.co.uk` still strips to `co.uk`, a Public-Suffix-List entry browsers also
+ * reject, so cross-subdomain auth would break (cookie dropped) rather than over-scope. A full PSL
+ * check would need a dependency, which this security-critical module deliberately avoids; for such
+ * apex domains set `betterAuth.crossSubDomainCookies.domain` explicitly instead of relying on
+ * derivation. See migration guide 11.27.5 → 11.27.6.
  */
 function deriveCookieDomainFromUrls(appUrl?: string, baseUrl?: string): string | undefined {
   // Priority 1: appUrl hostname (this IS the parent domain in typical setups)
@@ -1204,11 +1281,9 @@ function deriveCookieDomainFromUrls(appUrl?: string, baseUrl?: string): string |
       if (hostname === 'localhost' || hostname === '127.0.0.1') {
         return undefined;
       }
-      // Strip api. prefix to get parent domain
-      if (hostname.startsWith('api.')) {
-        return hostname.substring(4);
-      }
-      return hostname;
+      // Strip api. prefix to get parent domain — but keep the host unchanged when stripping
+      // would leave a bare TLD (`api.dev`) or empty host (`api.`).
+      return strippedApiHostname(hostname) ?? hostname;
     } catch {
       return undefined;
     }

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';