@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/data-source.runtime.ts

@@ -0,0 +1,351 @@
+import { Logger } from '@nestjs/common';
+
+import { ConfigService } from '../services/config.service.js';
+import { RequestContext } from '../services/request-context.service.js';
+import type { DataStore } from './data-store.interface.js';
+import { expiredRecordsFilter } from './expiry-sweep.js';
+import type { LockStore } from './lock-store.interface.js';
+import {
+  redactUrl,
+  type ResolvedDataSource,
+  type ResolvedDataSources,
+  resolveModelSource,
+} from './data-source.config.js';
+import type { ModelDescriptor } from './model-descriptor.interface.js';
+import { getModelDescriptor } from './model-metadata.registry.js';
+import { MongooseDataStore } from './mongoose-data-store.js';
+import {
+  getPersistedModels,
+  type IamSqlStorage,
+  type PersistenceOverview,
+  type PersistenceRuntime,
+} from './persistence-runtime.registry.js';
+import { grantStatement } from './sql/postgres/postgres-schema.compiler.js';
+import { assertSafeApplicationRole, SCHEMA_LOCK_SQL } from './sql/postgres/postgres-schema.migrator.js';
+import { type SqlDialect, sqlDialect } from './sql/sql-dialect.js';
+import { createSqlExecutor } from './sql/sql-executor.factory.js';
+import type { SqlExecutor } from './sql/sql-executor.interface.js';
+import { LOCK_MODEL, type SchemaChange, tableName } from './sql/sql-schema.shared.js';
+
+/**
+ * Routes every model registered with `CorePersistenceModule.forFeature()` to its data source (plan §3.9: the
+ * configuration, then `@PersistedModel`, then the default). A SQL source is connected once, as the application role;
+ * each model's table is brought up to date when its store is created — as the owner, or only verified without
+ * `ownerUrl` — and the application role is checked against it: a role row-level security cannot bind stops the boot.
+ * Per model, not per registry: the registry is process-wide, the stores Nest creates belong to THIS application.
+ * What differs between PostgreSQL and MySQL / MariaDB is the source's `SqlDialect`.
+ * Installed by `CoreModule.forRoot()` only when a SQL source is configured.
+ */
+export class DataSourceRuntime implements PersistenceRuntime {
+  protected readonly logger = new Logger('DataSources');
+  private bootReleased = false;
+  private readonly dialects = new Map<string, SqlDialect>();
+  private readonly executors = new Map<string, Promise<SqlExecutor>>();
+  /** Sources whose application-only tenant isolation was reported */
+  private readonly isolationReported = new Set<string>();
+  private lockStore?: Promise<LockStore | undefined>;
+  private readonly owners = new Map<string, Promise<SqlExecutor>>();
+  private readonly stores = new Map<string, Promise<DataStore<any>>>();
+
+  constructor(protected readonly resolved: ResolvedDataSources) {}
+
+  async close(): Promise<void> {
+    const executors = [...this.executors.values()];
+    this.executors.clear();
+    this.lockStore = undefined;
+    this.stores.clear();
+    await Promise.all([this.releaseBootConnections(), ...executors.map(closeExecutor)]);
+  }
+
+  /**
+   * The framework's own leases (system-setup claim, cron, migrations) live in the default source. Opened once — as the
+   * owner it brings the lease table up to date, which a model of the default source would otherwise have done
+   */
+  defaultLockStore(): Promise<LockStore | undefined> {
+    this.lockStore ??= this.openLockStore();
+    return this.lockStore;
+  }
+
+  async releaseBootConnections(): Promise<void> {
+    this.bootReleased = true;
+    const owners = [...this.owners.values()];
+    this.owners.clear();
+    await Promise.all(owners.map(closeExecutor));
+  }
+
+  async resolveStore(name: string, mongoModel: unknown): Promise<DataStore<any>> {
+    const source = this.sourceOf(name);
+    if (!source || source.driver === 'mongodb') {
+      return new MongooseDataStore(mongoModel as any);
+    }
+    let store = this.stores.get(name);
+    if (!store) {
+      store = this.openStore(source, name);
+      this.stores.set(name, store);
+    }
+    return store;
+  }
+
+  defaultSqlSource(): undefined | { engine?: string; ownerUrl?: string; url: string } {
+    const name = this.resolved.defaultSource;
+    const source = name ? this.resolved.sources[name] : undefined;
+    return source && source.driver !== 'mongodb'
+      ? { engine: source.sqlEngine, ownerUrl: source.ownerUrl, url: source.url }
+      : undefined;
+  }
+
+  describe(): PersistenceOverview {
+    return {
+      defaultSource: this.resolved.defaultSource,
+      models: getPersistedModels().map((model) => ({
+        name: model.name,
+        source: resolveModelSource(this.resolved, model.name, model.declaredSource),
+      })),
+      sources: Object.values(this.resolved.sources).map((source) => ({
+        driver: source.driver,
+        engine: source.sqlEngine,
+        host: redactUrl(source.url),
+        name: source.name,
+        ownerConfigured: !!source.ownerUrl,
+      })),
+    };
+  }
+
+  async iamStorage(): Promise<IamSqlStorage | undefined> {
+    const registration = getPersistedModels().find((model) => {
+      const descriptor = getModelDescriptor(model.name);
+      return !!descriptor && tableName(descriptor) === USERS_TABLE;
+    });
+    const source = registration ? this.sourceOf(registration.name) : undefined;
+    if (!registration || !source || source.driver === 'mongodb') {
+      return undefined;
+    }
+    if (source.driver !== 'postgres') {
+      throw new Error(
+        `Better-Auth cannot run on ${this.dialect(source).label} yet: the user model (table ${USERS_TABLE}) is routed to ` +
+          `the source "${source.name}". Keep the user model on PostgreSQL or MongoDB (database.models), or switch Better-Auth off.`,
+      );
+    }
+    // Opening the store brings `users` up to date first: Better-Auth only adds its columns to the table the user model
+    // defines, never the other way round
+    const users = await this.resolveStore(registration.name, undefined);
+    const app = await this.executor(source);
+    return {
+      applySchema: (migrate, tables) => this.applyForeignSchema(source, app, migrate, tables),
+      pool: app.driverPool,
+      source: source.name,
+      users,
+    };
+  }
+
+  async sweepExpired(now = new Date()): Promise<{ deleted: number; model: string }[]> {
+    const swept: { deleted: number; model: string }[] = [];
+    const failed: string[] = [];
+    for (const [name, pending] of this.stores) {
+      const descriptor = getModelDescriptor(name);
+      const expired = descriptor ? expiredRecordsFilter(descriptor, now) : undefined;
+      if (!expired) {
+        continue;
+      }
+      try {
+        const store = await pending;
+        // System work across every tenant, as the TTL monitor is: row-level security admits the system scope
+        const deleted = await RequestContext.runWithBypassTenantGuard(() => store.deleteMany(expired as any));
+        swept.push({ deleted, model: name });
+      } catch (error) {
+        // One table that cannot be swept must not keep the others full
+        failed.push(`${name}: ${(error as Error)?.message ?? error}`);
+      }
+    }
+    if (failed.length) {
+      throw new Error(failed.join('; '));
+    }
+    return swept;
+  }
+
+  sqlSources(): { name: string; ping: () => Promise<void> }[] {
+    return Object.values(this.resolved.sources)
+      .filter((source) => source.driver !== 'mongodb')
+      .map((source) => ({
+        name: source.name,
+        ping: async () => {
+          await (await this.executor(source)).run({ params: [], text: 'SELECT 1' }, { kind: 'system' });
+        },
+      }));
+  }
+
+  /**
+   * Whether a model's rows are tenant-isolated: tenant-scoped, multi-tenancy on, not excluded. On PostgreSQL the table
+   * carries row-level security; MySQL / MariaDB have none, and the store alone isolates
+   */
+  isTenantIsolated(model: ModelDescriptor): boolean {
+    const multiTenancy = ConfigService.configFastButReadOnly?.multiTenancy;
+    return (
+      !!multiTenancy &&
+      multiTenancy.enabled !== false &&
+      model.tenantScoped &&
+      !multiTenancy.excludeSchemas?.includes(model.name)
+    );
+  }
+
+  protected sourceOf(name: string): ResolvedDataSource | undefined {
+    const registration = getPersistedModels().find((model) => model.name === name);
+    const source = resolveModelSource(this.resolved, name, registration?.declaredSource);
+    return source ? this.resolved.sources[source] : undefined;
+  }
+
+  private async openStore(source: ResolvedDataSource, name: string): Promise<DataStore<any>> {
+    const model = getModelDescriptor(name);
+    if (!model) {
+      throw new Error(`No descriptor for model "${name}" — register it with CorePersistenceModule.forFeature()`);
+    }
+    const app = await this.executor(source);
+    const dialect = this.dialect(source);
+    let changes: SchemaChange[];
+    if (source.ownerUrl) {
+      changes = await dialect.applySchema(await this.owner(source), app, [model]);
+    } else {
+      changes = await dialect.verifySchema(app, [model]);
+    }
+    for (const change of changes) {
+      if (change.kind === 'automatic') {
+        this.logger.log(`[${source.name}] ${change.description}`);
+      } else if (change.kind === 'notice') {
+        this.logger.warn(`[${source.name}] ${change.description}`);
+      }
+    }
+    await dialect.assertSafeApplication(app, [tableName(model), tableName(LOCK_MODEL)]);
+    const isolated = this.isTenantIsolated(model);
+    if (isolated && source.driver !== 'postgres' && !this.isolationReported.has(source.name)) {
+      this.isolationReported.add(source.name);
+      this.logger.warn(
+        `[${source.name}] ${dialect.label} has no row-level security: tenant isolation of ${source.name} is enforced by ` +
+          'the application only. A query on a tenant table through store.native(), store.raw() or a connection of your ' +
+          'own must filter by tenantId itself — nothing in the database stops it.',
+      );
+    }
+    this.logger.log(
+      `${name} → ${source.name} → ${source.driver} ${redactUrl(source.url)} → ${source.sqlEngine}${dialect.isolation(isolated)}`,
+    );
+    const registration = getPersistedModels().find((entry) => entry.name === name);
+    return dialect.createStore(app, model, { schema: registration?.schema as any });
+  }
+
+  private async openLockStore(): Promise<LockStore | undefined> {
+    const name = this.resolved.defaultSource;
+    const source = name ? this.resolved.sources[name] : undefined;
+    if (!source || source.driver === 'mongodb') {
+      return undefined;
+    }
+    const app = await this.executor(source);
+    const dialect = this.dialect(source);
+    if (!source.ownerUrl) {
+      await dialect.verifySchema(app, []);
+    } else if (this.bootReleased) {
+      // First asked after the boot released its owner connections: a connection of its own, closed at once
+      const owner = await createSqlExecutor({
+        applicationName: 'nest-server-schema',
+        engine: source.sqlEngine,
+        maxConnections: 1,
+        url: source.ownerUrl,
+      });
+      try {
+        await dialect.applySchema(owner, app, []);
+      } finally {
+        await owner.close();
+      }
+    } else {
+      await dialect.applySchema(await this.owner(source), app, []);
+    }
+    await dialect.assertSafeApplication(app, [tableName(LOCK_MODEL)]);
+    return dialect.createLockStore(app);
+  }
+
+  /**
+   * Tables another library creates in a SQL source (Better-Auth's): its migration runs as the owner under the schema lock
+   * the framework's own evolution takes, so replicas booting together apply it once; the application role is granted
+   * and checked as on the framework's tables. Two owner connections: one holds the lock, the library migrates on the
+   * other — it brings its own client and cannot run inside the locking transaction.
+   */
+  private async applyForeignSchema(
+    source: ResolvedDataSource,
+    app: SqlExecutor,
+    migrate: (pool: unknown, asOwner: boolean) => Promise<void>,
+    tables: string[],
+  ): Promise<void> {
+    if (!source.ownerUrl) {
+      await migrate(app.driverPool, false);
+    } else {
+      const connect = (maxConnections: number) =>
+        createSqlExecutor({
+          applicationName: 'nest-server-schema',
+          engine: source.sqlEngine,
+          maxConnections,
+          url: source.ownerUrl,
+        });
+      const [lock, migrator] = await Promise.all([connect(1), connect(2)]);
+      const appRole = decodeURIComponent(new URL(source.url).username);
+      try {
+        await lock.transaction(async (tx) => {
+          await tx.run({ params: [], text: SCHEMA_LOCK_SQL }, SYSTEM);
+          await migrate(migrator.driverPool, true);
+          for (const table of tables) {
+            await tx.run({ params: [], text: grantStatement(table, appRole) }, SYSTEM);
+          }
+        });
+      } finally {
+        await Promise.all([lock.close(), migrator.close()]);
+      }
+    }
+    await assertSafeApplicationRole(app, tables);
+  }
+
+  private dialect(source: ResolvedDataSource): SqlDialect {
+    let dialect = this.dialects.get(source.name);
+    if (!dialect) {
+      dialect = sqlDialect({
+        appRole: decodeURIComponent(new URL(source.url).username),
+        driver: source.driver as 'mariadb' | 'mysql' | 'postgres',
+        isTenantIsolated: (candidate) => this.isTenantIsolated(candidate),
+      });
+      this.dialects.set(source.name, dialect);
+    }
+    return dialect;
+  }
+
+  /**
+   * One owner connection per source for the whole boot, released once every store exists: one per model opened and
+   * closed a privileged connection for every table, and the stores are created concurrently
+   */
+  private owner(source: ResolvedDataSource): Promise<SqlExecutor> {
+    let pending = this.owners.get(source.name);
+    if (!pending) {
+      pending = createSqlExecutor({
+        applicationName: 'nest-server-schema',
+        engine: source.sqlEngine,
+        maxConnections: 1,
+        url: source.ownerUrl,
+      });
+      this.owners.set(source.name, pending);
+    }
+    return pending;
+  }
+
+  private executor(source: ResolvedDataSource): Promise<SqlExecutor> {
+    let pending = this.executors.get(source.name);
+    if (!pending) {
+      pending = createSqlExecutor({ applicationName: 'nest-server', engine: source.sqlEngine, url: source.url });
+      this.executors.set(source.name, pending);
+    }
+    return pending;
+  }
+}
+
+/** The table the user model and Better-Auth share */
+const USERS_TABLE = 'users';
+
+const SYSTEM = { kind: 'system' } as const;
+
+async function closeExecutor(pending: Promise<SqlExecutor>): Promise<void> {
+  await (await pending.catch(() => undefined))?.close();
+}

package/src/core/common/persistence/data-store.interface.ts

@@ -0,0 +1,155 @@
+/**
+ * The data store port: the neutral operations every database implements.
+ *
+ * Import-free on purpose (types only), like every leaf the persistence layer and its DI tokens depend on.
+ *
+ * Records are plain objects with the id as a string under `id` (never `_id`, never a driver type). Filters
+ * and updates use the Mongo-operator subset the codebase already speaks: MongoDB executes them as they
+ * are, a SQL store compiles them and refuses what it cannot express — it never drops a condition.
+ */
+
+/**
+ * Neutral filter: implicit equality, dot paths into embedded objects, and the operators
+ * `$eq $ne $gt $gte $lt $lte $in $nin $exists $regex/$options $and $or $nor $not $all $size $elemMatch`.
+ * The id is addressed as `id`.
+ */
+export type Where<T = Record<string, any>> = { [K in keyof T]?: any } & {
+  [path: string]: any;
+  $and?: Where<T>[];
+  $nor?: Where<T>[];
+  $or?: Where<T>[];
+};
+
+/**
+ * Neutral update: a partial record (equivalent to `$set`), or the operators `$set $unset $inc $push
+ * $pull $addToSet $setOnInsert`.
+ */
+export type DataStoreUpdate<T = Record<string, any>> =
+  | Partial<T>
+  | {
+      $addToSet?: Record<string, unknown>;
+      $inc?: Record<string, number>;
+      $pull?: Record<string, unknown>;
+      $push?: Record<string, unknown>;
+      $set?: Partial<T> & Record<string, unknown>;
+      $setOnInsert?: Partial<T> & Record<string, unknown>;
+      $unset?: Record<string, '' | 1 | true>;
+    };
+
+/** A stored record: the model's fields plus its id as a string. */
+export type StoredRecord<T = Record<string, any>> = T & { id: string };
+
+export interface FindOptions {
+  /** Language-specific string comparison (MongoDB collation; mapped by SQL stores where supported) */
+  collation?: Record<string, unknown>;
+  limit?: number;
+  /**
+   * Return this many records chosen at random from the page — after filter, sort, skip and limit, as MongoDB's `$sample`
+   * stage follows them in `CrudService.findAndCount()`. A positive integer; a sample larger than the page returns the
+   * whole page. The order of the result is random too.
+   */
+  sample?: number;
+  /**
+   * Field names to leave out (MongoDB's `-name` projection); everything else the model returns by default is read.
+   * Not combinable with `select`, as MongoDB does not combine them either.
+   */
+  exclude?: readonly string[];
+  /** Field names to return; the id is always returned */
+  select?: readonly string[];
+  skip?: number;
+  /** Field → 1 (ascending) or -1 (descending), applied in declaration order */
+  sort?: Record<string, -1 | 1>;
+}
+
+export interface UpdateOptions {
+  /**
+   * `false` leaves the update time (`updatedAt`) as it is — for bookkeeping writes such as a last-used stamp, which
+   * must not read as a change of the record (Mongoose's `timestamps: false`). @default true
+   */
+  timestamps?: boolean;
+}
+
+export interface PushOptions {
+  /** Insert position (MongoDB `$position`) */
+  position?: number;
+  /** Keep only this many items after the push: negative = the last n, positive = the first n */
+  slice?: number;
+  /** Sort the array after the push */
+  sort?: Record<string, -1 | 1>;
+}
+
+/**
+ * What a store can do. Features ask the store, never the driver name; an unavailable capability fails at
+ * boot when it is configured and at the call with a named error otherwise.
+ */
+export interface StoreCapabilities {
+  /** `aggregate()` with a MongoDB pipeline */
+  aggregatePipeline: boolean;
+  /** Change streams / logical replication feed */
+  changeFeed: boolean;
+  /** GridFS file storage */
+  gridfs: boolean;
+  /** Mongoose documents and populate — the CrudService pipeline's MongoDB path */
+  mongoosePopulate: boolean;
+  /** A raw driver filter is passed through untouched */
+  rawFilterArm: boolean;
+  /** Row-level security enforced by the database */
+  rls: boolean;
+  /** Full-text search */
+  textSearch: boolean;
+  /** Multi-statement transactions */
+  transactions: boolean;
+  /** Format of generated ids */
+  idType: 'objectId';
+}
+
+export interface DataStore<T = Record<string, any>> {
+  readonly capabilities: StoreCapabilities;
+  /** The database behind the store (`mongodb`, `postgres`, …) */
+  readonly driver: string;
+  readonly modelName: string;
+
+  count(where?: Where<T>): Promise<number>;
+  deleteById(id: string): Promise<null | StoredRecord<T>>;
+  /** Remove every record matching `where`; returns how many were removed. */
+  deleteMany(where: Where<T>): Promise<number>;
+  /**
+   * Remove the first record matching `where`, atomically (MongoDB's `findOneAndDelete`), and return it; `null` when
+   * nothing matches.
+   */
+  deleteOne(where: Where<T>): Promise<null | StoredRecord<T>>;
+  distinct(field: string, where?: Where<T>): Promise<unknown[]>;
+  find(where?: Where<T>, options?: FindOptions): Promise<StoredRecord<T>[]>;
+  findById(id: string, options?: Pick<FindOptions, 'exclude' | 'select'>): Promise<null | StoredRecord<T>>;
+  findOne(where: Where<T>, options?: Omit<FindOptions, 'limit' | 'skip'>): Promise<null | StoredRecord<T>>;
+  insert(record: Partial<T>): Promise<StoredRecord<T>>;
+  /**
+   * Tier 2 access: the database library's own API for this model (the Mongoose model on MongoDB), bound
+   * to the current unit of work. The reason is mandatory and logged.
+   */
+  native<N = unknown>(reason: string): N;
+  /** Remove every array item matching `condition` from `field`, atomically. */
+  pullFromArray(id: string, field: string, condition: unknown): Promise<void>;
+  /** Append `items` to the array `field`, atomically. */
+  pushToArray(id: string, field: string, items: readonly unknown[], options?: PushOptions): Promise<void>;
+  /**
+   * Tier 3 access: the raw driver (the MongoDB collection on MongoDB). Bypasses every policy of the
+   * store; the reason is mandatory and logged as a security event.
+   */
+  raw<N = unknown>(reason: string): N;
+  /**
+   * How many records match `where`, and the total of the numeric `field` over them (a missing value adds 0) — counted
+   * by the database, so only the result crosses the wire (MongoDB's `$group`, SQL's `count`/`sum`).
+   */
+  sum(field: string, where?: Where<T>): Promise<{ count: number; sum: number }>;
+  /** Apply `update` to the record and return it as stored afterwards; `null` when there is none. */
+  updateById(id: string, update: DataStoreUpdate<T>, options?: UpdateOptions): Promise<null | StoredRecord<T>>;
+  /** Apply `update` to every record matching `where`; returns how many records matched. */
+  updateMany(where: Where<T>, update: DataStoreUpdate<T>): Promise<number>;
+  /**
+   * Apply `update` to the first record matching `where`, atomically: the record still matches when it is changed, and
+   * concurrent callers never change the same record on the strength of one match (MongoDB's `findOneAndUpdate`).
+   * Returns the record as stored afterwards; `null` when nothing matches.
+   */
+  updateOne(where: Where<T>, update: DataStoreUpdate<T>): Promise<null | StoredRecord<T>>;
+}

package/src/core/common/persistence/expiry-sweep.ts

@@ -0,0 +1,105 @@
+import type { Logger } from '@nestjs/common';
+
+import { defaultSqlLockStore } from './infrastructure-locks.js';
+import type { ModelDescriptor } from './model-descriptor.interface.js';
+
+/**
+ * How often expired rows are removed from SQL tables. MongoDB's TTL monitor does this for its collections about once a
+ * minute; on SQL nothing does it unless the framework does. Nothing depends on it for correctness — every reader checks
+ * the expiry itself — so the interval only bounds how long expired rows take up space.
+ */
+export const EXPIRY_SWEEP_INTERVAL_MS = 15 * 60_000;
+
+/**
+ * The records of a model whose TTL has passed, decided as MongoDB's TTL monitor decides it: a non-array date field plus
+ * its TTL lies before `now` — a record without that date never expires — and, for a PARTIAL TTL index, the record also
+ * matches the index's `partialFilterExpression`, because MongoDB expires nothing outside it. `undefined` when the model
+ * declares no TTL.
+ *
+ * The partial filter is not decoration: `{ expireAfterSeconds, partialFilterExpression: { verified: false } }` expires
+ * unverified accounts only, and a sweep that dropped the filter deleted every verified one as well. A filter the SQL
+ * where compiler cannot express makes the delete fail, so nothing is deleted rather than too much.
+ */
+export function expiredRecordsFilter(model: ModelDescriptor, now: Date): Record<string, unknown> | undefined {
+  const conditions = Object.values(model.fields)
+    .filter(
+      (field) =>
+        field.kind === 'date' &&
+        !field.isArray &&
+        Number.isFinite(field.expiresAfterSeconds) &&
+        field.expiresAfterSeconds >= 0,
+    )
+    .map((field) => {
+      const expired = { [field.name]: { $lt: new Date(now.getTime() - field.expiresAfterSeconds * 1000) } };
+      const ttlIndex = model.indexes.find(
+        (index) =>
+          Object.keys(index.fields).length === 1 && field.name in index.fields && 'expireAfterSeconds' in index.options,
+      );
+      const partial = ttlIndex?.options.partialFilterExpression as Record<string, unknown> | undefined;
+      return partial ? { $and: [expired, partial] } : expired;
+    });
+  if (!conditions.length) {
+    return undefined;
+  }
+  return conditions.length === 1 ? conditions[0] : { $or: conditions };
+}
+
+/** A scheduled sweep */
+export interface ExpirySweep {
+  /** Sweep at once, without the lease — after the sweep that may be running has finished */
+  runNow(): Promise<void>;
+  /** End the timer and wait for a sweep that is still running */
+  stop(): Promise<void>;
+}
+
+/**
+ * Run `sweep` now and then every `intervalMs` — on one replica per interval when the default source is a SQL database
+ * (the lease `expiry-sweep:<key>` in its lease table, never released, so the next replica takes it once it expired),
+ * otherwise on every replica. Running it on several is harmless: a sweep only deletes what has already expired.
+ *
+ * Fails open: a sweep or a lease that fails is logged and tried again at the next interval, it never stops the
+ * application.
+ */
+export function scheduleExpirySweep(
+  key: string,
+  sweep: () => Promise<void>,
+  options: { intervalMs?: number; logger: Logger },
+): ExpirySweep {
+  const intervalMs = options.intervalMs ?? EXPIRY_SWEEP_INTERVAL_MS;
+  const owner = `expiry-sweep:${process.pid}:${Math.random().toString(36).slice(2)}`;
+  let running: Promise<void> | undefined;
+
+  const tick = async (): Promise<void> => {
+    try {
+      const locks = await defaultSqlLockStore('expiry-sweep');
+      if (locks && !(await locks.tryAcquire(key, owner, Math.max(1, Math.floor(intervalMs / 1000))))) {
+        return;
+      }
+      await sweep();
+    } catch (error) {
+      options.logger.warn(
+        `Expiry sweep "${key}" failed, trying again in ${Math.max(1, Math.round(intervalMs / 60_000))} min: ${(error as Error)?.message ?? error}`,
+      );
+    }
+  };
+  const run = () => {
+    // One sweep at a time: an interval that elapses during a slow sweep is skipped, not queued
+    running ??= tick().finally(() => {
+      running = undefined;
+    });
+  };
+
+  run();
+  const timer = setInterval(run, intervalMs);
+  timer.unref();
+  return {
+    runNow: async () => {
+      await running;
+      await sweep();
+    },
+    stop: async () => {
+      clearInterval(timer);
+      await running;
+    },
+  };
+}

package/src/core/common/persistence/id-format.ts

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+
+import { isObjectIdLike } from '../helpers/id.helper.js';
+
+export { isObjectIdLike } from '../helpers/id.helper.js';
+
+/**
+ * The stored id format, the same on every database: 24 hex characters — an ObjectId's hex string.
+ * On MongoDB that IS the ObjectId; on SQL the application generates it (plan §3.5), so ids, URLs and
+ * validators stay identical across the fleet and survive a data move between databases.
+ */
+const STORED_ID = /^[0-9a-f]{24}$/i;
+
+/**
+ * Whether a value is a well-formed stored id: an ObjectId (from any bson copy) or its 24-character hex
+ * string.
+ *
+ * Deliberately stricter than `Types.ObjectId.isValid()`, which also accepts any 12-character string
+ * (a 12-byte ObjectId seed) — no stored id ever has that form. For strings this is exactly the rule
+ * `checkStringIds()` and `CoreFileService.isMalformedFileId()` applied as `length === 24 && isValid()`.
+ */
+export function isWellFormedId(value: unknown): boolean {
+  if (typeof value === 'string') {
+    return STORED_ID.test(value);
+  }
+  return isObjectIdLike(value);
+}
+
+const PROCESS_UNIQUE = randomBytes(5);
+let counter = randomBytes(3).readUIntBE(0, 3);
+
+/**
+ * A new id in the stored format, generated by the application (plan §3.5): an ObjectId — 4 bytes of seconds,
+ * 5 random bytes per process, a 3-byte counter — so ids stay sortable by creation time like MongoDB's.
+ */
+export function generateId(): string {
+  const bytes = Buffer.alloc(12);
+  bytes.writeUInt32BE(Math.floor(Date.now() / 1000) >>> 0, 0);
+  PROCESS_UNIQUE.copy(bytes, 4);
+  counter = (counter + 1) % 0x1000000;
+  bytes.writeUIntBE(counter, 9, 3);
+  return bytes.toString('hex');
+}