@lenne.tech/nest-server 12.1.1 → 12.3.0

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

@@ -0,0 +1,85 @@
+/**
+ * The wire format of the sync protocol (`docs/offline-sync-protocol.md`) and the hook of the `custom` strategy.
+ * Types only.
+ */
+
+/** A pushed change (protocol §6.2) */
+export interface ISyncPushItem {
+  /** The version the change is based on; absent only on the item that creates the record */
+  baseVersion?: number;
+  /** The fields to set (`upsert`); validated against the model's input like any create/update */
+  data?: Record<string, unknown>;
+  /** For `merge`: the field names the client changed. Without it, every key in `data` counts as changed */
+  fields?: string[];
+  /** The record's id, in the model's format */
+  id: string;
+  /** Unique per change, generated by the client; the same change sent again carries the same id */
+  mutationId: string;
+  op: SyncPushOp;
+}
+
+export type SyncPushOp = 'delete' | 'upsert';
+
+/** Protocol §7 */
+export type SyncItemStatus = 'applied' | 'conflict' | 'merged' | 'not_found' | 'rejected' | 'retry';
+
+/** Protocol §7 — the reason of a `rejected` item */
+export type SyncRejectCode = 'CUSTOM_REFUSED' | 'FORBIDDEN' | 'ID_UNAVAILABLE' | 'INVALID_ID' | 'VALIDATION_FAILED';
+
+/**
+ * A record as a pull delivers it (protocol §5.2): a live record carries its content in `data`, a tombstone carries
+ * no `data` — only its id, version, times, `tenantId` and the model's scope fields (protocol §2).
+ */
+export interface ISyncRecord {
+  [scopeField: string]: unknown;
+  data?: Record<string, unknown>;
+  deletedAt: Date | null;
+  id: string;
+  updatedAt?: Date;
+  version: number;
+}
+
+/** Protocol §6.6 */
+export interface ISyncPushResult {
+  code?: SyncRejectCode;
+  details?: unknown;
+  id: string;
+  mutationId: string;
+  /** The server's record (`conflict`, `merged`) */
+  record?: ISyncRecord;
+  status: SyncItemStatus;
+  version?: number;
+}
+
+/** Protocol §5.2 */
+export interface ISyncPullResult {
+  cursor: string;
+  hasMore: boolean;
+  items: ISyncRecord[];
+}
+
+/** Protocol §8 */
+export type SyncResyncReason = 'access' | 'horizon' | 'invalid';
+
+/** What `resolveSyncConflict()` receives under the `custom` strategy */
+export interface ISyncConflictContext {
+  /** What the client sent */
+  change: { baseVersion?: number; data?: Record<string, unknown>; fields?: string[]; op: SyncPushOp };
+  /** The authenticated caller, as the controller received it */
+  currentUser: any;
+  id: string;
+  model: string;
+  /** The record as the caller may see it now, a live record (a tombstone always conflicts) */
+  server: ISyncRecord;
+}
+
+/**
+ * The answer of `resolveSyncConflict()`: the fields to write on top of the server's record, a deletion, or a refusal
+ * (`rejected` / `CUSTOM_REFUSED`). The write runs through the same pipeline as every push.
+ */
+export type SyncConflictResolution = { data: Record<string, unknown> } | { delete: true } | { refuse: true };
+
+/** A model service whose model declares `strategy: 'custom'` implements this */
+export interface SyncConflictResolver {
+  resolveSyncConflict(context: ISyncConflictContext): Promise<SyncConflictResolution> | SyncConflictResolution;
+}

package/src/core/modules/sync/models/core-sync-hint.model.ts

@@ -0,0 +1,18 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../../common/enums/role.enum.js';
+
+/**
+ * A change hint of offline sync (protocol §9): the model changed at this time — nothing else, no record, no id, no
+ * tenant. A client answers it with a pull. Who receives it was decided before it was sent.
+ */
+@ObjectType('SyncHint', { description: 'A synchronized model changed: pull it' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class CoreSyncHintModel {
+  @Field(() => Date, { description: 'When the change was sent' })
+  at: Date;
+
+  @Field(() => String, { description: 'The changed model, as in GET /sync/{model}' })
+  model: string;
+}

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

@@ -26,6 +26,7 @@ import {
 import { DataSourceConfigError } from '../../common/persistence/data-source.config.js';
 import type { DataStore } from '../../common/persistence/data-store.interface.js';
 import { getStoreToken } from '../../common/persistence/persistence.tokens.js';
+import { getSyncAccessListener } from '../../common/persistence/sync-access.registry.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
@@ -383,6 +384,13 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   invalidateTenant(tenantId: string): void {
     this.clearTenant(tenantId);
     this.publishInvalidation({ scope: 'tenant', tenantId });
+    // Offline sync: the tenant's members resync on their next pull (a no-op without the sync module). Once, here —
+    // the epoch lives in the database, so a replica receiving the broadcast must not bump it again
+    void getSyncAccessListener()
+      ?.tenantInvalidated(tenantId)
+      .catch((error) =>
+        this.logger.warn(`Sync access epoch of tenant ${tenantId} not bumped: ${(error as Error)?.message ?? error}`),
+      );
   }
 
   /**
@@ -803,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');
+  }
 }
 
 /**

package/src/core.module.ts

@@ -84,6 +84,7 @@ import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config
 import { CorePermissionsModule } from './core/modules/permissions/core-permissions.module.js';
 import { CoreSystemSetupModule } from './core/modules/system-setup/core-system-setup.module.js';
 import { CoreApiTokenModule } from './core/modules/api-token/core-api-token.module.js';
+import { CoreSyncModule } from './core/modules/sync/core-sync.module.js';
 import { CoreTenantModule } from './core/modules/tenant/core-tenant.module.js';
 
 /** Configuration warnings of `forRoot()`, through Nest's logger so log levels and a project's logger apply. */
@@ -676,6 +677,30 @@ export class CoreModule implements NestModule {
       imports.push(CoreApiTokenModule.forRoot({ ...overrides?.apiToken }));
     }
 
+    // Add CoreSyncModule when sync is configured (boolean shorthand, presence implies enabled). Without it nothing of
+    // offline sync is registered: no route, no infrastructure model, no listener on the write paths.
+    const syncConfig = config.sync;
+    if (
+      syncConfig === true ||
+      (typeof syncConfig === 'object' && syncConfig !== null && syncConfig.enabled !== false)
+    ) {
+      imports.push(
+        CoreSyncModule.forRoot({
+          ...overrides?.sync,
+          // The subscription needs GraphQL, and is switched off with its channel or with all hints
+          graphQlHints:
+            config.graphQl !== false &&
+            !(
+              typeof syncConfig === 'object' &&
+              (syncConfig.hints === false ||
+                (typeof syncConfig.hints === 'object' &&
+                  (syncConfig.hints.graphql === false || syncConfig.hints.enabled === false)))
+            ),
+          path: typeof syncConfig === 'object' ? syncConfig.path : undefined,
+        }),
+      );
+    }
+
     // Set exports
     const exports: any[] = [
       ConfigService,

package/src/index.ts

@@ -98,6 +98,8 @@ export * from './core/common/persistence/mongoose-data-store.js';
 export * from './core/common/persistence/persisted-model.decorator.js';
 export * from './core/common/persistence/persistence.tokens.js';
 export * from './core/common/persistence/persistence-runtime.registry.js';
+export { VersionConflictError } from './core/common/persistence/policies/sync.policy.js';
+export * from './core/common/persistence/sync-model.js';
 export * from './core/common/persistence/unsupported-capability.error.js';
 export * from './core/common/persistence/sql/mysql/mysql-data-store.js';
 export * from './core/common/persistence/sql/mysql/mysql-lock-store.js';
@@ -276,6 +278,25 @@ export * from './core/modules/system-setup/core-system-setup.controller.js';
 export * from './core/modules/system-setup/core-system-setup.module.js';
 export * from './core/modules/system-setup/core-system-setup.service.js';
 
+// =====================================================================================================================
+// Core - Modules - Sync (offline sync)
+// =====================================================================================================================
+
+export * from './core/modules/sync/core-sync-base.controller.js';
+export * from './core/modules/sync/core-sync.constants.js';
+export * from './core/modules/sync/core-sync.controller.js';
+export * from './core/modules/sync/core-sync.decorators.js';
+export * from './core/modules/sync/core-sync-hints.controller.js';
+export * from './core/modules/sync/core-sync-hints.service.js';
+export * from './core/modules/sync/core-sync-infrastructure.models.js';
+export * from './core/modules/sync/core-sync.module.js';
+export * from './core/modules/sync/core-sync-mutation.store.js';
+export * from './core/modules/sync/core-sync.resolver.js';
+export * from './core/modules/sync/core-sync.service.js';
+export * from './core/modules/sync/core-sync-state.store.js';
+export * from './core/modules/sync/interfaces/core-sync.interfaces.js';
+export * from './core/modules/sync/models/core-sync-hint.model.js';
+
 // =====================================================================================================================
 // Core - Modules - Tus
 // =====================================================================================================================

package/src/server/modules/sync-note/inputs/sync-note-create.input.ts

@@ -0,0 +1,14 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../../core/common/decorators/restricted.decorator.js';
+import { UnifiedField } from '../../../../core/common/decorators/unified-field.decorator.js';
+import { RoleEnum } from '../../../../core/common/enums/role.enum.js';
+import { SyncNoteInput } from './sync-note.input.js';
+
+/** Input of a pushed note that creates it; the client chose its id (protocol §3) */
+@InputType({ description: 'Input to create a synchronized note' })
+@Restricted(RoleEnum.ADMIN)
+export class SyncNoteCreateInput extends SyncNoteInput {
+  @UnifiedField({ description: 'Title of the note', roles: RoleEnum.S_EVERYONE })
+  override title: string = undefined;
+}