@lenne.tech/nest-server 12.2.0 → 12.3.1

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

@@ -2,6 +2,7 @@ import { Injectable, Logger, Optional } from '@nestjs/common';
 
 import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
+import { canonicalRequestPath, pathContainsSegments } from './core-better-auth-path-guard.middleware.js';
 import {
   InMemoryRateLimitStore,
   rateLimitKey,
@@ -134,10 +135,10 @@ export class CoreBetterAuthRateLimiter {
    * Check if a request is allowed under the rate limit
    *
    * @param ip - Client IP address
-   * @param path - Request path (relative to basePath)
+   * @param requestPath - Request path (relative to basePath), as sent; dot segments are resolved here
    * @returns Rate limit check result
    */
-  async check(ip: string, path: string): Promise<RateLimitResult> {
+  async check(ip: string, requestPath: string): Promise<RateLimitResult> {
     // If rate limiting is disabled, always allow
     if (!this.config.enabled) {
       return {
@@ -149,6 +150,13 @@ export class CoreBetterAuthRateLimiter {
       };
     }
 
+    // Decide on the path the request is served under, not the one as sent: `/callback/../sign-in/email` reaches the
+    // sign-in handler, so it must not be skipped as a callback (CoreBetterAuthPathGuardMiddleware refuses such paths
+    // before they get here; this keeps the limiter correct where that guard is not registered). Lower-cased because
+    // Express routes case-insensitively: `/sign-in/EMAIL` is the same sign-in and must share its counter and its
+    // strict limit
+    const path = canonicalRequestPath(requestPath).toLowerCase();
+
     // Check if this endpoint should skip rate limiting
     if (this.shouldSkip(path)) {
       return {
@@ -249,10 +257,11 @@ export class CoreBetterAuthRateLimiter {
   }
 
   /**
-   * Determine if an endpoint should skip rate limiting
+   * Determine if an endpoint should skip rate limiting: an entry matches whole path segments, so `/session` skips
+   * `/session` but not `/sessions-export`
    */
   private shouldSkip(path: string): boolean {
-    return this.config.skipEndpoints.some((skip) => path === skip || path.endsWith(skip) || path.includes(skip));
+    return this.config.skipEndpoints.some((skip) => pathContainsSegments(path, skip.toLowerCase()));
   }
 
   /**
@@ -260,9 +269,7 @@ export class CoreBetterAuthRateLimiter {
    * Strict endpoints get half the normal limit
    */
   private getLimit(path: string): number {
-    const isStrict = this.config.strictEndpoints.some(
-      (strict) => path === strict || path.endsWith(strict) || path.includes(strict),
-    );
+    const isStrict = this.config.strictEndpoints.some((strict) => pathContainsSegments(path, strict.toLowerCase()));
 
     return isStrict ? Math.ceil(this.config.max / 2) : this.config.max;
   }

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

@@ -39,6 +39,7 @@ import { DefaultBetterAuthResolver } from './better-auth.resolver.js';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware.js';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service.js';
 import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service.js';
+import { CoreBetterAuthPathGuardMiddleware } from './core-better-auth-path-guard.middleware.js';
 import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit.middleware.js';
 import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service.js';
 import { revokeApiTokensOfUser } from '../api-token/core-api-token.registry.js';
@@ -431,8 +432,10 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * 1. CoreBetterAuthMiddleware - Session validation and user mapping for all routes
    *    Must run FIRST so that req.betterAuthSession is available for downstream middleware.
    *    In JWT mode, this resolves the JWT to a real DB session (via getActiveSessionForUser).
-   * 2. CoreBetterAuthRateLimitMiddleware - Rate limiting for auth endpoints
-   * 3. CoreBetterAuthApiMiddleware - Forwards plugin endpoints (passkey, 2FA, etc.) to Better Auth's native handler
+   * 2. CoreBetterAuthPathGuardMiddleware - Refuses a non-canonical path under the base path (400), before
+   *    anything below reads it
+   * 3. CoreBetterAuthRateLimitMiddleware - Rate limiting for auth endpoints
+   * 4. CoreBetterAuthApiMiddleware - Forwards plugin endpoints (passkey, 2FA, etc.) to Better Auth's native handler
    *    Runs AFTER session middleware so it can use req.betterAuthSession.session.token
    *    to authenticate requests in JWT mode.
    */
@@ -453,6 +456,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       consumer.apply(CoreBetterAuthMiddleware).forRoutes('{*path}');
       CoreBetterAuthModule.logger.debug('CoreBetterAuthMiddleware registered for all routes');
 
+      // Refuse a non-canonical path (`.` / `..` segments, also encoded, backslashes, encoded slashes) before anything
+      // under the base path reads it: every check below reads the path as SENT, while Better-Auth routes the one
+      // `new URL()` resolved — `/callback/../sign-in/email` would pass the rate limiter as a callback and run as a
+      // sign-in. Registered unconditionally and FIRST, so it guards the limiter, the controller routes and the
+      // forwarding alike.
+      consumer.apply(CoreBetterAuthPathGuardMiddleware).forRoutes(`${basePath}/*path`);
+
       // Apply rate limiting to Better-Auth endpoints only.
       // Mirrors the "presence implies enabled" contract `CoreBetterAuthRateLimiter.configure()`
       // implements. Gating the MOUNT on `.enabled` alone made that fix unobservable: the limiter

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

@@ -34,6 +34,7 @@ export * from './core-better-auth-email-verification.service.js';
 export * from './core-better-auth-error-codes.helper.js';
 export * from './core-better-auth-migration-status.model.js';
 export * from './core-better-auth-models.js';
+export * from './core-better-auth-path-guard.middleware.js';
 export * from './core-better-auth-rate-limit.middleware.js';
 export * from './core-better-auth-rate-limiter.service.js';
 export * from './core-better-auth-signup-validator.service.js';

package/src/core/modules/error-code/error-codes.ts

@@ -494,6 +494,15 @@ export const LtnsErrors = {
     },
   },
 
+  INVALID_REQUEST_PATH: {
+    code: 'LTNS_0305',
+    message: 'Invalid request path',
+    translations: {
+      de: 'Der Anfragepfad ist ungültig.',
+      en: 'The request path is invalid.',
+    },
+  },
+
   // =====================================================
   // Resource Errors (LTNS_0400-LTNS_0499)
   // =====================================================
@@ -713,6 +722,15 @@ export const LtnsErrors = {
     },
   },
 
+  AI_SETTING_ENFORCED: {
+    code: 'LTNS_0609',
+    message: 'This AI setting is fixed by the server',
+    translations: {
+      de: 'Diese KI-Einstellung ist vom Server festgelegt und kann nicht geändert werden.',
+      en: 'This AI setting is fixed by the server and cannot be changed.',
+    },
+  },
+
   // =====================================================
   // Offline Sync Errors (LTNS_0700-LTNS_0799)
   // =====================================================

package/src/core/modules/sync/README.md

@@ -104,6 +104,13 @@ hashed, unique), records the outcome afterwards and answers a repeat with that o
 A repeat that finds a claim still being written answers `retry` — that is how two tabs sending the same push end in one
 write and no false conflict. A claim older than 30 s belongs to a request that died and is taken over.
 
+Once an item of a record is not stored (`conflict`, `rejected`, `not_found`, `retry`), the later items of that record
+in the same push are **held back** (12.3.0+): each builds on the version the one before it produces (protocol §6.2), and
+applied on its own its base version could match what another writer left. A held-back item is never applied or
+claimed; it is answered `retry` behind a `retry`, otherwise `conflict` with the record as the caller may see it
+(`not_found` without one). Items of other records are unaffected. This holds within one push; across pushes the
+client keeps the order (protocol §11).
+
 ## Change order and windows
 
 The store decides how changes are ordered (`capabilities.changeOrder`): on SQL a commit-ordered sequence (`syncSeq`) —
@@ -133,7 +140,10 @@ A hint tells a connected client that pulling is worthwhile; sync works without t
 - **Long-lived channels are re-checked:** the GraphQL subscription runs on the WebSocket `CoreModule` re-checks; an SSE
   stream is registered in the same registry and ends at once on an invalidation naming the caller or their tenant, and
   otherwise before the first hint after `graphQl.subscriptionRevalidationMs` — the EventSource reconnects (`retry`) and
-  the new request passes the guards. A client pulls once after every (re)connect.
+  the new request passes the guards. A client pulls once after every (re)connect. In the log the planned end after the
+  interval is a debug line (`Closing SSE hint stream of user …: re-check interval reached, client reconnects`); an end
+  an invalidation brings stays at `log` (`… authorization invalidated, client reconnects`), so a real revocation stands
+  out (12.3.0; before, every planned end read `Closing GraphQL WebSocket …: Session no longer valid`).
 
 ## Tombstone purge
 

package/src/core/modules/sync/core-sync.service.ts

@@ -157,7 +157,7 @@ const SYSTEM_RECORD_FIELDS = new Set([
 ]);
 
 /**
- * Offline sync (protocol `docs/offline-sync-protocol.md`, plan `.claude/plans/offline-sync/PLAN.md`): pull in pages
+ * Offline sync (protocol `docs/offline-sync-protocol.md`, offline-sync plan): pull in pages
  * along the store's change order, push item by item with idempotency, conflict strategies and client ids, resync when a
  * cursor cannot be continued consistently.
  *
@@ -686,17 +686,61 @@ export class CoreSyncService implements OnApplicationBootstrap, OnModuleDestroy,
   /**
    * Apply the pushed items in the order sent, each on its own (protocol §6.3) — one result per item. A malformed body
    * is refused as a whole before any item is applied.
+   *
+   * A later item of a record carries the version the item before it produces (§6.2). Once an item of a record was not
+   * stored, the later items of that record are held back: applied on their own, their base version could match what
+   * another writer left, and the change would land on data the client never saw.
    */
   async push(model: string, body: unknown, currentUser: any): Promise<{ results: ISyncPushResult[] }> {
     const registration = this.registration(model);
     const items = this.pushItems(body);
     const results: ISyncPushResult[] = [];
+    const heldBack = new Map<string, 'refused' | 'retry'>();
     for (const item of items) {
-      results.push(await this.pushItem(registration, item, currentUser));
+      const held = heldBack.get(item.id);
+      if (held) {
+        results.push(await this.heldBackItem(registration, item, held, currentUser));
+        continue;
+      }
+      const result = await this.pushItem(registration, item, currentUser);
+      if (result.status === 'retry') {
+        heldBack.set(item.id, 'retry');
+      } else if (result.status !== 'applied' && result.status !== 'merged') {
+        heldBack.set(item.id, 'refused');
+      }
+      results.push(result);
     }
     return { results };
   }
 
+  /**
+   * An item held back behind an earlier item of its record that was not stored. It is never applied and never claimed,
+   * so a repeat of the batch is answered the same way (the earlier item repeats its recorded outcome). Behind a
+   * `retry` it is `retry` too, and the client sends both again; behind a refusal it is the conflict the `reject`
+   * strategy answers — the record as the caller may see it, `not_found` without one.
+   */
+  protected async heldBackItem(
+    registration: SyncModelRegistration,
+    item: ISyncPushItem,
+    reason: 'refused' | 'retry',
+    currentUser: any,
+  ): Promise<ISyncPushResult> {
+    if (!isSyncId(item.id, registration.idFormat)) {
+      return reply(item, 'rejected', { code: 'INVALID_ID' });
+    }
+    if (reason === 'retry') {
+      return reply(item, 'retry');
+    }
+    try {
+      return await this.currentConflict(registration, item, currentUser);
+    } catch (error) {
+      this.logger.warn(
+        `Sync: ${registration.name} ${item.id} held back, record unreadable, client retries (${(error as Error)?.message ?? error})`,
+      );
+      return reply(item, 'retry');
+    }
+  }
+
   /** The items of a push body, checked for shape; anything malformed answers 400 for the whole request */
   protected pushItems(body: unknown): ISyncPushItem[] {
     const invalid = (reason: string) => new BadRequestException(`${ErrorCode.SYNC_INVALID_REQUEST}: ${reason}`);
@@ -1412,8 +1456,9 @@ export class CoreSyncService implements OnApplicationBootstrap, OnModuleDestroy,
     response.once?.('close', end);
     registerWsConnection({
       carrier,
+      channel: 'SSE hint stream',
       // No credential to check again: every re-check ends the stream, and the reconnect is checked by the guards
-      reauthenticate: () => undefined,
+      endsOnRecheck: true,
       socket: {
         close: () => end(),
         once: (event, listener) => {

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -175,6 +175,16 @@ See [Tenant README — BetterAuth Integration](./README.md#betterauth-iam-integr
 
 See the module README: "Deactivated Tenants" and "Service-Level Role Checks".
 
+### 12. Removing a Tenant (since 12.3.0)
+
+- **Can a tenant be deleted in your project?** Call `tenantService.purgeTenantData(tenantId)` where the project deletes
+  its tenant record, after deleting the tenant's files through `CoreFileService`. WHY: the core has no tenant model and
+  cannot notice the deletion; until the purge runs, the tenant's API tokens keep authenticating and its records stay.
+- **Does a model reference the tenant in a field other than `tenantId`?** Override `purgeTenantRecords()` and call
+  `super`. WHY: the purge finds `tenantId` paths and the core's own references only.
+
+See the module README: "Removing a Tenant".
+
 ## Verification Checklist
 
 - [ ] `pnpm run build` succeeds
@@ -206,4 +216,5 @@ See the module README: "Deactivated Tenants" and "Service-Level Role Checks".
 | Public endpoint accessing tenantId-schema        | 403 Safety Net exception           | Use `@SkipTenantCheck()` + `RequestContext.runWithBypassTenantGuard()`     |
 | Passing user-supplied tenantId to create()       | Cross-tenant write possible        | Let plugin auto-set tenantId from context                                  |
 | Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |
-| `@SkipTenantCheck()` on BetterAuth handler       | Redundant since v11.21.2           | Remove — auto-skip handles this via `betterAuth.skipTenantCheck` (default) |
+| `@SkipTenantCheck()` on BetterAuth handler       | Redundant since v11.21.2           | Remove — auto-skip handles this via `betterAuth.skipTenantCheck` (default) |
+| Deleting only the tenant record                  | Tenant tokens and records survive  | Call `purgeTenantData(tenantId)` when the tenant is deleted                |

package/src/core/modules/tenant/README.md

@@ -391,6 +391,51 @@ Mechanism, for anyone extending the guard (`core-tenant.guard.ts`):
 - **A received broadcast clears locally and does NOT re-publish** (`applyInvalidation()` → `clearUser()` / `clearAll()`, the no-broadcast variants). Re-publishing would bounce the message around the cluster forever.
 - **Publishing is fire-and-forget and failures are debug-level only.** A missed broadcast is not an error: it merely leaves the other replicas' caches stale until their TTL — exactly the no-Redis behaviour. Nothing about a request path depends on the broadcast succeeding.
 
+### Removing a Tenant (`purgeTenantData`, since 12.3.0)
+
+The core has no tenant model, so it cannot notice that a project deleted one — but it knows every place where it
+stores tenant data itself. When the project deletes its tenant record, it calls:
+
+```typescript
+const report = await this.tenantService.purgeTenantData(tenantId);
+// { TenantMember: 4, Invoice: 120, ApiToken: 2, AiConnection: 1 } — models with nothing to delete are left out
+
+// Count first, e.g. for a confirmation dialog:
+await this.tenantService.purgeTenantData(tenantId, { dryRun: true });
+
+// Leave a model alone (in addition to multiTenancy.excludeSchemas):
+await this.tenantService.purgeTenantData(tenantId, { exclude: ['AuditEntry'] });
+```
+
+| Step | What is deleted                                                                                                                                                                                                                                              |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1    | Every way in, so nobody writes into the tenant while its data goes: each membership in any status (`deleteAllMembers()`), its cached access invalidated at once — on every replica with Redis — and the tenant's API tokens (`tenant`), which need no member |
+| 2    | Every model registered with `CorePersistenceModule.forFeature()` that has a `tenantId` path, on whatever database it is routed to — the project's own models included                                                                                        |
+| 3    | Models with a `tenantId` path registered only through `MongooseModule.forFeature()` (MongoDB)                                                                                                                                                                |
+| 4    | Core models that name the tenant in another field: AI budget limits, connection preferences, tool grants and tool policies (`scope: 'tenant'`, `refId`)                                                                                                      |
+| 5    | AI connections: one only this tenant could use is deleted; from a shared one only the tenant is removed. An empty `tenantIds` list means "every tenant", so emptying it would hand the connection to all of them                                             |
+
+Not deleted:
+
+- models in `multiTenancy.excludeSchemas` — a `tenantId` there is not ownership — and models named in `exclude`;
+- users (the `users` table or collection): they are global and may belong to other tenants. That holds where `User`
+  carries a `tenantId` too (per-tenant users): delete those through the user service before the purge, which also
+  ends their Better-Auth sessions and accounts;
+- **files**: the file metadata carries no `tenantId`, and only the project knows which files (GridFS, S3, file system)
+  belonged to the tenant. Delete them through `CoreFileService` before the purge (a TUS upload records
+  `metadata.tenantId`);
+- references the core does not know of, e.g. a `companyId` field. Add them by overriding the protected
+  `purgeTenantRecords()` and calling `super`.
+
+The memberships cannot be excluded. Records go in batches of 1000 ids, so a large tenant never holds a synchronized
+model's change lock (and with it every other tenant's writes to that model) for the whole purge. A synchronized model
+(offline sync) keeps a tombstone per deleted record until the tombstone purge removes it. The purge runs as a system operation (no tenant filter), so call it only from a route that
+checked who may delete the tenant.
+
+`tenantGuard.invalidateTenant(tenantId)` clears the tenant's cached memberships as well (since 12.3.0). Before, it
+forgot only the `isTenantActive` answer, so memberships removed without `invalidateUser()` kept counting for up to
+`cacheTtlMs`.
+
 ### SkipTenantCheck
 
 For high-frequency endpoints that don't access tenant-scoped data, use `@SkipTenantCheck()` to avoid the membership lookup entirely.
@@ -466,9 +511,10 @@ this module:
   global roles removed (no admin bypass), optionally restricted to one tenant and capped by
   `maxTenantRole`.
 
-Both are denied on routes without `@ApiTokenScopes()`. **Call `CoreApiTokenService.deleteAllForTenant()`
-when you delete a tenant — nothing does it for you**: the core has no tenant model to notice the
-deletion, and a tenant token does not depend on any member, so it keeps authenticating until then.
+Both are denied on routes without `@ApiTokenScopes()`. **When you delete a tenant, call
+`CoreTenantService.purgeTenantData()` (or at least `CoreApiTokenService.deleteAllForTenant()`)** — the core has no
+tenant model to notice the deletion, and a tenant token does not depend on any member, so it keeps authenticating
+until then.
 
 ## Related
 

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

@@ -811,11 +811,27 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   }
 
   /**
-   * Forget a tenant's cached `isTenantActive` answer locally (no broadcast), and re-check the open
-   * WebSocket connections scoped to it.
+   * Forget everything cached about a tenant locally (no broadcast): its `isTenantActive` answer, the cached
+   * memberships in it and every cached tenant list that contains it. Then re-check the open WebSocket connections
+   * scoped to it.
+   *
+   * The memberships matter for a tenant that is gone rather than switched off: when its memberships were removed
+   * without `invalidateUser()`, a cached membership kept it reachable until `cacheTtlMs` ran out. A tenant switched off
+   * through `isTenantActive` needs only the active flag, which every membership path asks right after.
    */
   protected clearTenant(tenantId: string): void {
     this.tenantActiveCache.delete(tenantId);
+    for (const key of this.membershipCache.keys()) {
+      // Key: `${userId}:${tenantId}` — user ids carry no ':', so the first one separates the two
+      if (key.slice(key.indexOf(':') + 1) === tenantId) {
+        this.membershipCache.delete(key);
+      }
+    }
+    for (const [key, entry] of this.tenantIdsCache.entries()) {
+      if (entry.ids.includes(tenantId)) {
+        this.tenantIdsCache.delete(key);
+      }
+    }
     revalidateWsConnectionsForTenant(tenantId);
   }