@lenne.tech/nest-server 12.2.0 → 12.3.0

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

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

@@ -1,11 +1,23 @@
 import { BadRequestException, Injectable, Logger, NotFoundException, Optional } from '@nestjs/common';
-import { InjectModel } from '../../common/persistence/mongo/mongoose-compat.js';
-import type { Model } from 'mongoose';
+import { InjectConnection, InjectModel } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection, Model } from 'mongoose';
 
 import { looksLikeGlobalOnlyRole, looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../common/enums/role.enum.js';
 import type { DataStore } from '../../common/persistence/data-store.interface.js';
+import { getModelDescriptors } from '../../common/persistence/model-metadata.registry.js';
+import { defaultCollectionName } from '../../common/persistence/mongo/collection-name.js';
+import { tableName } from '../../common/persistence/sql/sql-schema.shared.js';
+import { getModelStore, getStoreForModel } from '../../common/persistence/persistence-runtime.registry.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { RequestContext } from '../../common/services/request-context.service.js';
+import {
+  AI_BUDGET_LIMIT_MODEL,
+  AI_CONNECTION_MODEL,
+  AI_CONNECTION_PREFERENCE_MODEL,
+  AI_TOOL_GRANT_MODEL,
+  AI_TOOL_POLICY_MODEL,
+} from '../ai/core-ai.constants.js';
+import { API_TOKEN_MODEL_TOKEN } from '../api-token/core-api-token.constants.js';
 import { CoreTenantMemberModel } from './core-tenant-member.model.js';
 import { routedMemberStore } from './core-tenant-member.store.js';
 import { DEFAULT_ROLE_HIERARCHY, TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums.js';
@@ -34,6 +46,14 @@ import { CoreTenantGuard } from './core-tenant.guard.js';
 export class CoreTenantService {
   protected readonly logger = new Logger(CoreTenantService.name);
 
+  /**
+   * The MongoDB connection, `null` without MongoDB. `purgeTenantData()` reads the models registered only through
+   * `MongooseModule.forFeature()` from it. Injected as a property, so a subclass constructor needs no change
+   */
+  @Optional()
+  @InjectConnection()
+  protected readonly mongoConnection?: Connection | null;
+
   constructor(
     @InjectModel(TENANT_MEMBER_MODEL_TOKEN) protected readonly memberModel: Model<CoreTenantMemberModel>,
     @Optional() protected readonly tenantGuard?: CoreTenantGuard,
@@ -298,6 +318,271 @@ export class CoreTenantService {
       }
     });
   }
+
+  /**
+   * Delete every membership of a tenant, whatever its status, and clear what the tenant guard cached for it.
+   *
+   * Meant for removing a tenant: unlike {@link removeMember} it deletes the rows instead of suspending them and skips
+   * the last-owner check, because the tenant itself goes. Every affected user is invalidated in the guard (on every
+   * replica with Redis), the tenant last. Answers how many memberships went.
+   */
+  async deleteAllMembers(tenantId: string): Promise<number> {
+    requireTenantId(tenantId);
+    return RequestContext.runWithBypassTenantGuard(async () => {
+      const where = { tenant: tenantId };
+      const store = this.memberDataStore();
+      const members = store ? await store.find(where) : await this.memberModel.find(where).select('user').lean().exec();
+      const deleted = store ? await store.deleteMany(where) : (await this.memberModel.deleteMany(where)).deletedCount;
+      for (const userId of new Set(members.map((member) => String(member.user)))) {
+        this.tenantGuard?.invalidateUser(userId);
+      }
+      this.tenantGuard?.invalidateTenant(tenantId);
+      return deleted;
+    });
+  }
+
+  /**
+   * Delete everything the framework knows to belong to a tenant. Answers how many records went per model (models with
+   * none are left out); with `dryRun` it only counts.
+   *
+   * First every way in ({@link endTenantAccess}): the memberships ({@link deleteAllMembers}) and the tenant's API
+   * tokens (`tenant`), which need no member — so nobody writes into the tenant while its data goes. Then, through
+   * {@link purgeTenantRecords}:
+   *
+   * - every model registered with `CorePersistenceModule.forFeature()` that has a `tenantId` path, on whatever
+   *   database it is routed to — the project's own models included;
+   * - models with a `tenantId` path registered only through `MongooseModule.forFeature()` (MongoDB);
+   * - the core models that reference a tenant without a `tenantId` path: the AI budget limits, connection preferences,
+   *   tool grants and tool policies (`scope: 'tenant'`, `refId`);
+   * - AI connections: one only this tenant could use is deleted, from a shared one the tenant is removed. Never the
+   *   other way round — an empty `tenantIds` list means "every tenant".
+   *
+   * Left out: models in `multiTenancy.excludeSchemas` (a `tenantId` there is no ownership), every model named in
+   * `exclude`, users — the `users` table or collection, also where users carry a `tenantId`: a project with per-tenant
+   * users deletes them through its user service, which also ends their Better-Auth sessions and accounts — and files:
+   * their bytes can only be assigned to a tenant by the project, which deletes them through `CoreFileService`. The
+   * memberships cannot be excluded. A synchronized model keeps a tombstone
+   * per deleted record until the tombstone purge removes it.
+   */
+  async purgeTenantData(tenantId: string, options: TenantPurgeOptions = {}): Promise<Record<string, number>> {
+    requireTenantId(tenantId);
+    const dryRun = options.dryRun === true;
+    const exclude = new Set([
+      ...(ConfigService.configFastButReadOnly?.multiTenancy?.excludeSchemas ?? []),
+      ...(options.exclude ?? []),
+    ]);
+    exclude.delete(this.memberModel.modelName);
+
+    // Access ends before the data goes
+    const access = await this.endTenantAccess(tenantId, { dryRun, exclude });
+    const records = await this.purgeTenantRecords(tenantId, { dryRun, exclude });
+
+    return Object.fromEntries(Object.entries({ ...access, ...records }).filter(([, count]) => count > 0));
+  }
+
+  /**
+   * End every way into a tenant (or with `dryRun` count it): the memberships, and the references that grant access on
+   * their own — the tenant's API tokens, which need no member. Runs before {@link purgeTenantRecords}, or a member or an
+   * integration with a tenant token writes into the tenant while its data goes
+   */
+  protected async endTenantAccess(
+    tenantId: string,
+    { dryRun, exclude }: { dryRun: boolean; exclude: ReadonlySet<string> },
+  ): Promise<Record<string, number>> {
+    const report: Record<string, number> = {
+      [this.memberModel.modelName]: dryRun ? await this.countMembers(tenantId) : await this.deleteAllMembers(tenantId),
+    };
+    await RequestContext.runWithBypassTenantGuard(() =>
+      this.purgeReferences(tenantId, { access: true, dryRun, exclude }, report),
+    );
+    return report;
+  }
+
+  /**
+   * Delete (or with `dryRun` count) a tenant's records in every model except what {@link endTenantAccess} handles. The
+   * place to add a project's own references: override it, call `super`, add the counts. Runs after the access is gone;
+   * `exclude` already holds `multiTenancy.excludeSchemas`
+   */
+  protected async purgeTenantRecords(
+    tenantId: string,
+    { dryRun, exclude }: { dryRun: boolean; exclude: ReadonlySet<string> },
+  ): Promise<Record<string, number>> {
+    const report: Record<string, number> = {};
+    await RequestContext.runWithBypassTenantGuard(async () => {
+      const handled = new Set<string>([
+        this.memberModel.modelName,
+        AI_CONNECTION_MODEL,
+        ...TENANT_REFERENCES.map((reference) => reference.model),
+      ]);
+
+      // Every routed model with a tenantId path
+      for (const [name, descriptor] of getModelDescriptors()) {
+        if (tableName(descriptor) === USERS_COLLECTION) {
+          handled.add(name);
+          continue;
+        }
+        const store =
+          descriptor.tenantScoped &&
+          !handled.has(name) &&
+          !exclude.has(name) &&
+          getModelStore(this.mongoConnection, name);
+        if (store) {
+          handled.add(name);
+          const where = { tenantId };
+          report[name] = dryRun ? await store.count(where) : await this.deleteInBatches(store, where);
+        }
+      }
+
+      // MongoDB models no store serves (registered only through MongooseModule.forFeature())
+      for (const [name, model] of Object.entries(this.mongoConnection?.models ?? {})) {
+        if (
+          !handled.has(name) &&
+          !exclude.has(name) &&
+          model.schema?.path('tenantId') &&
+          (model.schema.get('collection') ?? defaultCollectionName(name)) !== USERS_COLLECTION
+        ) {
+          const where = { tenantId };
+          report[name] = dryRun ? await model.countDocuments(where) : (await model.deleteMany(where)).deletedCount;
+        }
+      }
+
+      // Core models that name the tenant in another field
+      await this.purgeReferences(tenantId, { access: false, dryRun, exclude }, report);
+
+      if (!exclude.has(AI_CONNECTION_MODEL)) {
+        report[AI_CONNECTION_MODEL] = await this.purgeTenantConnections(tenantId, dryRun);
+      }
+    });
+    return report;
+  }
+
+  /** The core references of {@link TENANT_REFERENCES} that do (`access`) or do not grant access, into `report` */
+  private async purgeReferences(
+    tenantId: string,
+    { access, dryRun, exclude }: { access: boolean; dryRun: boolean; exclude: ReadonlySet<string> },
+    report: Record<string, number>,
+  ): Promise<void> {
+    for (const reference of TENANT_REFERENCES) {
+      const store =
+        !!reference.access === access &&
+        !exclude.has(reference.model) &&
+        getModelStore(this.mongoConnection, reference.model);
+      if (store) {
+        const where = reference.where(tenantId);
+        report[reference.model] = dryRun ? await store.count(where) : await this.deleteInBatches(store, where);
+      }
+    }
+  }
+
+  /**
+   * Take a tenant out of the AI connections: delete a connection only this tenant could use, remove the tenant from
+   * the list of a shared one. Never empty a list — an empty `tenantIds` means "every tenant", so that would hand the
+   * connection, API key included, to all of them. Answers how many connections were touched
+   */
+  protected async purgeTenantConnections(tenantId: string, dryRun: boolean): Promise<number> {
+    const store = getModelStore(this.mongoConnection, AI_CONNECTION_MODEL);
+    if (!store) {
+      return 0;
+    }
+    const connections = await store.find({ tenantIds: { $all: [tenantId] } });
+    if (dryRun) {
+      return connections.length;
+    }
+    for (const connection of connections) {
+      const remaining = (connection.tenantIds ?? []).filter((id: string) => id !== tenantId);
+      if (remaining.length === 0) {
+        await store.deleteById(connection.id);
+      } else {
+        await store.updateById(connection.id, { tenantIds: remaining });
+      }
+    }
+    return connections.length;
+  }
+
+  /**
+   * Delete what `where` matches in batches of {@link TENANT_PURGE_BATCH} ids, as the tombstone purge does. One statement
+   * over all of a tenant's rows of a synchronized SQL model holds the model's change lock until it commits, and every
+   * other tenant's writes to that model wait for it. Answers how many records went
+   */
+  protected async deleteInBatches(store: DataStore<any>, where: Record<string, unknown>): Promise<number> {
+    let deleted = 0;
+    let after: string | undefined;
+    for (;;) {
+      const batch = await store.find(
+        { ...where, ...(after ? { id: { $gt: after } } : {}) },
+        { limit: TENANT_PURGE_BATCH, select: ['id'], sort: { id: 1 } },
+      );
+      if (!batch.length) {
+        return deleted;
+      }
+      deleted += await store.deleteMany({ ...where, id: { $in: batch.map((record) => record.id) } });
+      if (batch.length < TENANT_PURGE_BATCH) {
+        return deleted;
+      }
+      after = batch[batch.length - 1].id;
+    }
+  }
+
+  /**
+   * The store serving the membership model on either database, or `undefined` for a model registered only through
+   * `MongooseModule.forFeature()` — then the Mongoose model is used
+   */
+  protected memberDataStore(): DataStore<any> | undefined {
+    return getStoreForModel(this.memberModel) ?? getModelStore(this.mongoConnection, this.memberModel.modelName);
+  }
+
+  /** How many memberships a tenant has, in any status */
+  protected countMembers(tenantId: string): Promise<number> {
+    const where = { tenant: tenantId };
+    const store = this.memberDataStore();
+    return RequestContext.runWithBypassTenantGuard(() =>
+      store ? store.count(where) : this.memberModel.countDocuments(where).exec(),
+    );
+  }
+}
+
+/** Options of {@link CoreTenantService.purgeTenantData} */
+export interface TenantPurgeOptions {
+  /** Only count what would be deleted */
+  dryRun?: boolean;
+  /** Model names to leave alone, in addition to `multiTenancy.excludeSchemas`. The memberships always go */
+  exclude?: string[];
+}
+
+/** Records `purgeTenantData()` deletes per statement */
+const TENANT_PURGE_BATCH = 1000;
+
+/**
+ * The table / collection the user model shares with Better-Auth. `purgeTenantData()` never deletes from it, also where
+ * users carry a `tenantId`: a user leaves through the user service, which also ends the Better-Auth sessions and accounts
+ */
+const USERS_COLLECTION = 'users';
+
+/**
+ * Core models that reference a tenant without a `tenantId` path, and how they name it. `access`: the record lets
+ * somebody into the tenant on its own, so it goes together with the memberships, before the data
+ */
+const TENANT_REFERENCES: ReadonlyArray<{
+  access?: boolean;
+  model: string;
+  where: (tenantId: string) => Record<string, unknown>;
+}> = [
+  // A tenant token needs no membership
+  { access: true, model: API_TOKEN_MODEL_TOKEN, where: (tenantId) => ({ tenant: tenantId }) },
+  { model: AI_BUDGET_LIMIT_MODEL, where: (tenantId) => ({ refId: tenantId, scope: 'tenant' }) },
+  { model: AI_CONNECTION_PREFERENCE_MODEL, where: (tenantId) => ({ refId: tenantId, scope: 'tenant' }) },
+  { model: AI_TOOL_GRANT_MODEL, where: (tenantId) => ({ refId: tenantId, scope: 'tenant' }) },
+  { model: AI_TOOL_POLICY_MODEL, where: (tenantId) => ({ refId: tenantId, scope: 'tenant' }) },
+];
+
+/**
+ * Refuse a tenant id a delete must not run with. `deleteMany({ tenantId: undefined })` matches every document on
+ * MongoDB, and an operator object (`{ $ne: null }`) would match every tenant
+ */
+function requireTenantId(tenantId: unknown): asserts tenantId is string {
+  if (typeof tenantId !== 'string' || !tenantId.trim()) {
+    throw new BadRequestException('tenantId must be a non-empty string');
+  }
 }
 
 /**