@lenne.tech/nest-server 12.1.1 → 12.3.0

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

@@ -0,0 +1,65 @@
+# Offline Sync — Security
+
+What the server guarantees, and what a client has to do itself. Offline sync puts a copy of the user's data on the
+device, outside the server's control: the server can decide what reaches a device, but only the client can remove it
+again. The protocol is in [`docs/offline-sync-protocol.md`](../../../../docs/offline-sync-protocol.md) (§11 client
+duties, §12 server guarantees), the module in [README.md](./README.md).
+
+## What the server enforces
+
+| Guarantee                   | How                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No path around the rights   | Every pull and push runs through the model's `CrudService` — `process()`, `@Restricted`, `securityCheck()`, the tenant policy, row-level security on PostgreSQL — with the operation roles the model declares (`@PersistedModel({ sync: { roles } })`). There is no lean read path                                                                                                                                                                                              |
+| No foreign data             | A pull never delivers a record or tombstone of another tenant or one the caller's rights hide. A push never changes one: an update or delete answers `not_found`, as for an unused id; a create on its id answers `ID_UNAVAILABLE`, the same answer for every reason, with no tenant, owner, content or deletion state. That an id is taken stays observable (protocol §3, decided O2) — ids generated as §3 requires cannot be guessed, and the push rate limit bounds probing |
+| Tombstones without content  | A tombstone keeps its id, `version`, `deletedAt`, `updatedAt`, `tenantId` and the user-id scope fields the model declares — nothing a user typed                                                                                                                                                                                                                                                                                                                                |
+| No hard delete              | `op: 'delete'` leaves a tombstone through the normal delete pipeline; removing data for good is the purge's alone, after the retention horizon moved past it                                                                                                                                                                                                                                                                                                                    |
+| Access loss is enforced     | A changed role, a removed membership or a record moved away answers the next pull with `410 access` while the caller may still pull the model. Once they may not pull it at all (pull roles withdrawn), or `X-Tenant-Id` names a tenant they left or that was deactivated, the pull answers `403`. Either way the client must drop its copies                                                                                                                                   |
+| Cookie pushes are CSRF-safe | `Content-Type: application/json` is required, and while cookies are in use a cross-site `Sec-Fetch-Site` or an untrusted `Origin` is refused (`403`)                                                                                                                                                                                                                                                                                                                            |
+| Hints say nothing           | `{ model, at }` only, delivered to callers with the pull roles and access to the tenant of the change; an open stream ends when its user's rights change                                                                                                                                                                                                                                                                                                                        |
+| Probing is bounded          | Per-user rate limits on pull and push; client ids carry 64 random bits (protocol §3), so the next id of a client cannot be guessed                                                                                                                                                                                                                                                                                                                                              |
+
+## What a client must do
+
+### On logout
+
+The device holds personal data the server no longer controls. When the user signs out, delete:
+
+- **every local record** of every synchronized model,
+- **the cursors** (they are bound to the user; another user's pull with them answers `410 invalid`),
+- **the outbox** — the unsent changes. Before signing out, tell the user that changes are still unsent and offer to
+  sync first; after signing out they cannot be pushed under this account anyway,
+- **the credential**: the bearer token from wherever it is stored. A cookie session ends through the server's sign-out
+  route, which also clears the cookie.
+
+In a browser that is the IndexedDB database (or the SQLite-WASM file in the OPFS) of the app; in a native or desktop
+app the SQLite file. Deleting the whole database is simpler and safer than deleting rows.
+
+### On an account switch
+
+Exactly as on logout, before the next user's first pull. A client that kept the previous user's records would show
+them to the next user until a resync — the server cannot reach into the device to prevent it.
+
+### On `410 access`
+
+Delete every local record of that model, keep the unsent changes, pull without a cursor, then push the kept changes
+(protocol §8). The records the user may no longer see are gone afterwards — which is the point.
+
+### On `403` on a pull
+
+The caller may no longer pull the model at all, or not in that tenant. Treat it like `410 access` for that model (and
+tenant): delete its local records and its cursor. The unsent changes cannot be pushed under this account any more —
+tell the user rather than retrying.
+
+### At rest
+
+- A browser app authenticates with the session cookie (`httpOnly`), not with a token in `localStorage`, where any
+  script injected into the page can read it.
+- A native app keeps its token in the OS keychain, never in the SQLite file next to the data.
+- A service worker caches the app shell only, never responses of `/sync` or `/iam` — the reference test client
+  (`tests/clients/pwa/sw.js` in the framework repository) shows the split.
+- Device encryption is the operating system's job; recommend it where the data is sensitive.
+
+### Ids
+
+Generate the ids of offline records with a secure random source (`crypto.getRandomValues`), as protocol §3 describes
+— never a driver's default `new ObjectId()`, whose next value is predictable from the last one.

package/src/core/modules/sync/core-sync-base.controller.ts

@@ -0,0 +1,43 @@
+import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+
+import { getTenantContextResolver } from '../../common/services/core-tenant-context.registry.js';
+import { ErrorCode } from '../error-code/error-codes.js';
+import { CoreSyncService } from './core-sync.service.js';
+
+/**
+ * What the sync routes share: the tenant scope of a header-less request and the per-user rate limit. Declares no route,
+ * so `CoreSyncController` (pull, push) and `CoreSyncHintsController` (hints) each register only their own.
+ *
+ * `@Injectable()` only so the constructor's parameter types are emitted: the two controllers inherit it.
+ */
+@Injectable()
+export abstract class CoreSyncBaseController {
+  constructor(protected readonly syncService: CoreSyncService) {}
+
+  /**
+   * Without `X-Tenant-Id` a sync request spans every tenant the caller is an active member of (plan §3.4) — or every
+   * tenant for an administrator under `adminBypass`. The tenant guard admits an `S_USER` route without resolving
+   * those memberships, so this asks the guard's own membership logic (`core-tenant-context.registry.ts`). A header
+   * the guard validated is kept; without multi-tenancy nothing happens.
+   */
+  protected async scopeTenants(req: any, currentUser: any): Promise<void> {
+    if (!req || !currentUser?.id || req.tenantId || req.tenantIds || req.isAdminBypass) {
+      return;
+    }
+    const resolved = await getTenantContextResolver()?.resolve(currentUser, undefined);
+    if (resolved?.isAdminBypass) {
+      req.isAdminBypass = true;
+    } else if (resolved?.tenantIds) {
+      req.tenantIds = resolved.tenantIds;
+    }
+  }
+
+  /** 429 with `Retry-After` once the caller exceeded the limit of this kind */
+  protected async limit(kind: 'pull' | 'push', currentUser: any, res: any): Promise<void> {
+    const retryAfter = await this.syncService.rateLimit(kind, currentUser);
+    if (retryAfter !== undefined) {
+      res?.setHeader?.('Retry-After', String(retryAfter));
+      throw new HttpException(ErrorCode.RATE_LIMIT_EXCEEDED, HttpStatus.TOO_MANY_REQUESTS);
+    }
+  }
+}

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

@@ -0,0 +1,117 @@
+import { createHash, createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+
+/**
+ * The pull cursor (protocol §5, plan §3.4): opaque to the client, signed by the server, bound to the model and the user
+ * it was issued for. Format: `base64url(JSON).base64url(HMAC-SHA256)`. Nothing in it is a secret — the signature only
+ * keeps a client from editing it into another user's, another model's or an earlier position.
+ */
+
+/** Where a pull continues */
+export type SyncCursorPosition =
+  /** SQL: the last change number delivered (`syncSeq`) */
+  | { seq: number }
+  /** MongoDB: the keyset `(syncAt, id)` of the last record delivered; `id: ''` starts at `at` itself */
+  | { at: number; id: string };
+
+export interface SyncCursorState {
+  /** Hash of the access epochs the cursor was issued under */
+  epochs: string;
+  /** Hash of the caller's access when the cursor was issued (user, tenant scope, roles, verification) */
+  fingerprint: string;
+  model: string;
+  position: SyncCursorPosition;
+  /** Start (epoch ms) of the run in progress; absent once a page ended its run */
+  runStart?: number;
+  /**
+   * Start (epoch ms) of the run since which the client's state is complete — compared with the tombstone horizon: a
+   * tombstone purged after this point may never have reached the client
+   */
+  since: number;
+  user: string;
+}
+
+/** Cursors longer than this are refused unread: nothing the server issues comes close */
+const MAX_CURSOR_LENGTH = 2048;
+
+/** The key the cursors are signed with, derived from the configured secret (never the secret itself) */
+export function deriveCursorKey(secret: string): Buffer {
+  return Buffer.from(hkdfSync('sha256', secret, 'lenne.tech', 'nest-server:sync-cursor:v1', 32));
+}
+
+export function encodeSyncCursor(state: SyncCursorState, key: Buffer): string {
+  const payload = Buffer.from(
+    JSON.stringify({
+      e: state.epochs,
+      f: state.fingerprint,
+      k: state.since,
+      m: state.model,
+      p: 'seq' in state.position ? { s: state.position.seq } : { a: state.position.at, i: state.position.id },
+      ...(state.runStart === undefined ? {} : { r: state.runStart }),
+      u: state.user,
+      v: 1,
+    }),
+  ).toString('base64url');
+  return `${payload}.${sign(payload, key)}`;
+}
+
+/** The cursor's state, or `undefined` when it is malformed, tampered with or of another format version */
+export function decodeSyncCursor(cursor: unknown, key: Buffer): SyncCursorState | undefined {
+  if (typeof cursor !== 'string' || !cursor || cursor.length > MAX_CURSOR_LENGTH) {
+    return undefined;
+  }
+  const [payload, signature, rest] = cursor.split('.');
+  if (!payload || !signature || rest !== undefined) {
+    return undefined;
+  }
+  const expected = Buffer.from(sign(payload, key));
+  const given = Buffer.from(signature);
+  if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
+    return undefined;
+  }
+  let raw: any;
+  try {
+    raw = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return undefined;
+  }
+  if (
+    !raw ||
+    raw.v !== 1 ||
+    typeof raw.m !== 'string' ||
+    typeof raw.u !== 'string' ||
+    typeof raw.f !== 'string' ||
+    typeof raw.e !== 'string' ||
+    !Number.isFinite(raw.k) ||
+    (raw.r !== undefined && !Number.isFinite(raw.r)) ||
+    !raw.p ||
+    typeof raw.p !== 'object'
+  ) {
+    return undefined;
+  }
+  let position: SyncCursorPosition;
+  if (Number.isFinite(raw.p.s)) {
+    position = { seq: raw.p.s };
+  } else if (Number.isFinite(raw.p.a) && typeof raw.p.i === 'string') {
+    position = { at: raw.p.a, id: raw.p.i };
+  } else {
+    return undefined;
+  }
+  return {
+    epochs: raw.e,
+    fingerprint: raw.f,
+    model: raw.m,
+    position,
+    ...(raw.r === undefined ? {} : { runStart: raw.r }),
+    since: raw.k,
+    user: raw.u,
+  };
+}
+
+/** A short, stable hash of a JSON-serializable value (fingerprints, epoch sets) */
+export function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('base64url').slice(0, 32);
+}
+
+function sign(payload: string, key: Buffer): string {
+  return createHmac('sha256', key).update(payload).digest('base64url');
+}

package/src/core/modules/sync/core-sync-hints.controller.ts

@@ -0,0 +1,52 @@
+import { Controller, Get, NotFoundException, Query, Req, Res } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import { CurrentUser } from '../../common/decorators/current-user.decorator.js';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { ErrorCode } from '../error-code/error-codes.js';
+import { CoreSyncBaseController } from './core-sync-base.controller.js';
+import { SYNC_DEFAULTS } from './core-sync.constants.js';
+
+/**
+ * `GET /sync/hints` (protocol §9): server-sent change hints. A controller of its own, registered before
+ * `CoreSyncController`: Nest registers a class's own routes before the ones it inherits, so a project controller that
+ * re-declares `pull()` (`@Get(':model')`) would otherwise read `hints` as a model name and answer 404 — and an
+ * EventSource does not reconnect after an error status, so the hints would stop without a sign.
+ *
+ * A signed-in caller always gets the stream (200); models the caller may not pull never send a hint, so the stream
+ * reveals nothing about which models exist. API tokens are refused here like on every route without
+ * `@ApiTokenScopes()`; a project that wants them extends this controller, re-declares `hints()` with
+ * `@ApiTokenScopes('sync')` and passes it as `sync.hintsController` override.
+ */
+@ApiTags('sync')
+@Controller(SYNC_DEFAULTS.path)
+@Roles(RoleEnum.S_USER)
+export class CoreSyncHintsController extends CoreSyncBaseController {
+  /** The stream is `CoreSyncService.openHintStream()`; 404 while the SSE channel is switched off */
+  @ApiBearerAuth()
+  @ApiOperation({
+    description:
+      'Server-sent events: `event: change` with `{ model, at }` whenever a model the caller may pull changes; ' +
+      '`models` (comma-separated) narrows the stream',
+    summary: 'Change hints (SSE)',
+  })
+  @Get('hints')
+  @Roles(RoleEnum.S_USER)
+  async hints(
+    @Query('models') models: string,
+    @CurrentUser() currentUser: any,
+    @Req() req: any,
+    @Res() res: any,
+  ): Promise<void> {
+    if (!this.syncService.hintsEnabled('sse')) {
+      throw new NotFoundException(ErrorCode.SYNC_MODEL_NOT_FOUND);
+    }
+    // Counted like a pull: an EventSource reconnects on its own, and every reconnect is a request
+    await this.limit('pull', currentUser, res);
+    // Without X-Tenant-Id the stream spans every membership of the caller, as a pull does
+    await this.scopeTenants(req, currentUser);
+    const named = typeof models === 'string' ? models.split(',').map((model) => model.trim()) : [];
+    await this.syncService.openHintStream(req, res, currentUser, named.filter(Boolean));
+  }
+}

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

@@ -0,0 +1,178 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy, Optional } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import type { ISync } from '../../common/interfaces/server-options.interface.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
+import { SYNC_DEFAULTS } from './core-sync.constants.js';
+
+/**
+ * A hint as the bus carries it: a synchronized model changed, in a tenant (`undefined` on a model without tenants).
+ * Subscribers receive `{ model, at }` only (plan §3.9); the tenant decides who receives it.
+ */
+export interface SyncHintEvent {
+  at: number;
+  model: string;
+  tenantId?: string;
+}
+
+/**
+ * The hint bus of offline sync (plan §3.9, protocol §9): a change of a synchronized model becomes one hint per model and
+ * tenant per `sync.hints.debounceMs`, delivered to this replica's subscribers at once and, with `redis`, to every other
+ * replica's through one Redis channel. Without Redis, or while it does not answer, hints stay on this replica — a hint
+ * only means "pull now", so a client that misses one learns of the change at its next pull.
+ *
+ * Who may receive a hint is not decided here: each subscriber filters by its own access (`CoreSyncService`).
+ */
+@Injectable()
+export class CoreSyncHintService implements OnApplicationBootstrap, OnModuleDestroy {
+  protected readonly logger = new Logger(CoreSyncHintService.name);
+  /** This replica, so a hint it published is not delivered a second time when Redis brings it back */
+  protected readonly origin = randomUUID();
+  protected readonly subscribers = new Set<(hint: SyncHintEvent) => void>();
+  /** Pending hints by model and tenant: one per key and debounce window, removed when sent */
+  protected readonly pending = new Map<string, ReturnType<typeof setTimeout>>();
+  protected channel?: string;
+  protected redisListener?: (channel: string, message: string) => void;
+
+  constructor(@Optional() protected readonly redisService?: CoreRedisService) {}
+
+  /** The `sync.hints` configuration (an object; `true` / absent read as `{}`, `false` as `{ enabled: false }`) */
+  protected get config(): Exclude<ISync['hints'], boolean | undefined> {
+    const sync = ConfigService.configFastButReadOnly?.sync;
+    const hints = sync && typeof sync === 'object' ? sync.hints : undefined;
+    if (hints === false) {
+      return { enabled: false };
+    }
+    return hints && typeof hints === 'object' ? hints : {};
+  }
+
+  /** Whether hints are sent at all (`sync.hints`, on by default) */
+  get enabled(): boolean {
+    return this.config.enabled !== false;
+  }
+
+  /** `sync.hints.debounceMs`: at most one hint per model and tenant per window; an invalid value → the default */
+  protected get debounceMs(): number {
+    const value = this.config.debounceMs;
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : SYNC_DEFAULTS.hintDebounceMs;
+  }
+
+  async onApplicationBootstrap(): Promise<void> {
+    if (!this.enabled || !this.redisService?.enabled) {
+      return;
+    }
+    const channel = this.redisService.key('sync', 'hints');
+    try {
+      // Held in a field: the subscriber connection is shared, a listener left behind would deliver into a destroyed bus
+      this.channel = channel;
+      this.redisListener = (incoming: string, message: string) => {
+        if (incoming === channel) {
+          this.receive(message);
+        }
+      };
+      this.redisService.getSubscriber().on('message', this.redisListener);
+      // Registered with the Redis service, so the subscription comes back after every reconnect
+      await this.redisService.subscribeChannel(channel);
+    } catch (error) {
+      this.logger.warn(
+        `Sync hints: Redis subscribe failed (${(error as Error)?.message ?? error}) — retried when the connection is ` +
+          "up; until then this replica's subscribers receive only its own hints",
+      );
+    }
+  }
+
+  onModuleDestroy(): void {
+    for (const timer of this.pending.values()) {
+      clearTimeout(timer);
+    }
+    this.pending.clear();
+    this.subscribers.clear();
+    if (this.redisListener) {
+      try {
+        this.redisService?.getSubscriber().off('message', this.redisListener);
+        if (this.channel) {
+          void this.redisService?.releaseChannel(this.channel).catch(() => undefined);
+        }
+      } catch {
+        // Redis already gone — nothing to detach from
+      }
+      this.redisListener = undefined;
+    }
+  }
+
+  /**
+   * A synchronized model changed in these tenants (none: a model without tenants). Sent as one hint per model and
+   * tenant once the debounce window ends — a burst of writes is one hint.
+   */
+  notify(model: string, tenantIds: readonly (string | undefined)[] = [undefined]): void {
+    if (!this.enabled) {
+      return;
+    }
+    for (const tenantId of tenantIds.length ? new Set(tenantIds) : [undefined]) {
+      const key = `${model}\u0000${tenantId ?? ''}`;
+      if (this.pending.has(key)) {
+        continue;
+      }
+      const timer = setTimeout(() => {
+        this.pending.delete(key);
+        this.send({ at: Date.now(), model, ...(tenantId ? { tenantId } : {}) });
+      }, this.debounceMs);
+      timer.unref?.();
+      this.pending.set(key, timer);
+    }
+  }
+
+  /** Receive every hint (this replica's and, with Redis, every other's); answers the unsubscribe */
+  subscribe(handler: (hint: SyncHintEvent) => void): () => void {
+    this.subscribers.add(handler);
+    return () => {
+      this.subscribers.delete(handler);
+    };
+  }
+
+  /** Deliver a hint here and hand it to the other replicas */
+  protected send(hint: SyncHintEvent): void {
+    this.deliver(hint);
+    if (!this.channel || !this.redisService?.enabled) {
+      return;
+    }
+    try {
+      void this.redisService
+        .getClient()
+        .publish(this.channel, JSON.stringify({ ...hint, origin: this.origin }))
+        .catch((error: Error) => this.logger.debug(`Sync hint publish failed: ${error.message}`));
+    } catch (error) {
+      this.logger.debug(`Sync hint publish failed: ${(error as Error)?.message ?? error}`);
+    }
+  }
+
+  /** A hint from the Redis channel — another replica's; this replica's own were delivered when sent */
+  protected receive(message: string): void {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(message);
+    } catch {
+      return;
+    }
+    if (!parsed || parsed.origin === this.origin || typeof parsed.model !== 'string' || !Number.isFinite(parsed.at)) {
+      return;
+    }
+    this.deliver({
+      at: Number(parsed.at),
+      model: parsed.model,
+      ...(typeof parsed.tenantId === 'string' && parsed.tenantId ? { tenantId: parsed.tenantId } : {}),
+    });
+  }
+
+  protected deliver(hint: SyncHintEvent): void {
+    // A Set tolerates a subscriber removing itself while it is called
+    for (const handler of this.subscribers) {
+      try {
+        handler(hint);
+      } catch (error) {
+        this.logger.warn(`Sync hint subscriber failed: ${(error as Error)?.message ?? error}`);
+      }
+    }
+  }
+}

package/src/core/modules/sync/core-sync-infrastructure.models.ts

@@ -0,0 +1,40 @@
+import { createSchema } from '../../common/persistence/mongo/mongoose-compat.js';
+
+/**
+ * The sync module's infrastructure stores (offline-sync plan §3.3 E7, §3.7) as framework models: registered with
+ * `CorePersistenceModule.forFeature()`, they follow `database` like every other model and run through one code path
+ * on every database — a collection on MongoDB, a table on SQL. Nothing here relies on the TTL for correctness: every
+ * reader checks `expiresAt` itself; MongoDB's TTL index and the SQL expiry sweep only reclaim the space.
+ */
+
+/**
+ * One pushed mutation per `key` (model, user, record, mutation id — hashed): claimed before the record is written
+ * (`state: 'pending'`), then its outcome (`state: 'done'` with `status`, `version`, `code`). `attempt` makes every
+ * takeover a conditional write that exactly one request wins.
+ */
+export const SyncMutationSchema = createSchema(
+  {
+    attempt: { type: Number },
+    claimedAt: { type: Date },
+    code: { type: String },
+    expiresAt: { index: { expireAfterSeconds: 0 }, type: Date },
+    key: { index: { unique: true }, type: String },
+    state: { type: String },
+    status: { type: String },
+    version: { type: Number },
+  },
+  { collection: 'syncMutations', versionKey: false },
+);
+
+/**
+ * Access epochs (`epoch:…` keys, an integer bumped when access to synchronized records changes, plan §3.8) and tombstone
+ * horizons (`horizon:<model>`, the oldest point a cursor may continue from, advanced by the purge before it deletes).
+ */
+export const SyncStateSchema = createSchema(
+  {
+    epoch: { type: Number },
+    horizon: { type: Date },
+    key: { index: { unique: true }, type: String },
+  },
+  { collection: 'syncStates', versionKey: false },
+);

package/src/core/modules/sync/core-sync-mutation.store.ts

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+
+import type { DataStore, StoredRecord } from '../../common/persistence/data-store.interface.js';
+
+/** The recorded outcome of a mutation: what a repeat of it is answered with (protocol §6.5) */
+export interface SyncMutationOutcome {
+  code?: string;
+  status: string;
+  version?: number;
+}
+
+/**
+ * What a claim found:
+ * - `claimed`: this request writes the mutation and then records its outcome (`complete()`) or gives it up (`release()`)
+ * - `busy`: another request is writing it right now — answer `retry`
+ * - `done`: it was applied before — answer with its outcome
+ */
+export type SyncMutationClaim = { kind: 'busy' } | { kind: 'claimed' } | { kind: 'done'; outcome: SyncMutationOutcome };
+
+interface MutationRecord {
+  attempt?: number;
+  claimedAt?: Date;
+  code?: null | string;
+  expiresAt?: Date;
+  key: string;
+  state?: string;
+  status?: null | string;
+  version?: null | number;
+}
+
+/**
+ * Idempotency of pushed changes (offline-sync plan §3.7): the mutation is claimed BEFORE the record is written, under a
+ * unique key, so two tabs sending the same change at once end in one write — the second finds the claim and is told to
+ * retry, then finds the outcome. A record written after the write could not give that: both requests would miss it.
+ *
+ * A claim older than the claim timeout belongs to a request that died between claiming and recording; it is taken over
+ * with a conditional write on `attempt`, which exactly one contender wins. An entry past `expiresAt` counts as absent
+ * whether or not the TTL has removed it yet.
+ */
+export class CoreSyncMutationStore {
+  constructor(
+    protected readonly store: DataStore<MutationRecord>,
+    protected readonly options: { claimTimeoutMs: number; retentionMs: number },
+  ) {}
+
+  /**
+   * The key of a mutation: model, user, record and mutation id, hashed to a fixed length. The user is part of it, so a
+   * mutation id of somebody else can neither block a change nor reveal its outcome.
+   */
+  static key(model: string, userId: string, recordId: string, mutationId: string): string {
+    return createHash('sha256').update([model, userId, recordId, mutationId].join('\u0000')).digest('hex');
+  }
+
+  async claim(key: string, now = new Date()): Promise<SyncMutationClaim> {
+    // A concurrent claimant can make each step fail once; three rounds settle every interleaving of two requests
+    for (let round = 0; round < 3; round++) {
+      const existing = await this.store.findOne({ key });
+      if (!existing) {
+        try {
+          await this.store.insert({ key, ...this.pending(now, 1) });
+          return { kind: 'claimed' };
+        } catch (error) {
+          if (!isDuplicateKey(error)) {
+            throw error;
+          }
+          continue;
+        }
+      }
+      if (isExpired(existing, now)) {
+        if (await this.takeOver(existing, now)) {
+          return { kind: 'claimed' };
+        }
+        continue;
+      }
+      if (existing.state === 'done' && existing.status) {
+        return { kind: 'done', outcome: outcomeOf(existing) };
+      }
+      const claimedAt = existing.claimedAt ? new Date(existing.claimedAt).getTime() : 0;
+      if (now.getTime() - claimedAt < this.options.claimTimeoutMs) {
+        return { kind: 'busy' };
+      }
+      return (await this.takeOver(existing, now)) ? { kind: 'claimed' } : { kind: 'busy' };
+    }
+    return { kind: 'busy' };
+  }
+
+  /** Record the outcome of a claimed mutation; kept for the retention period from now */
+  async complete(key: string, outcome: SyncMutationOutcome, now = new Date()): Promise<void> {
+    await this.store.updateOne(
+      { key },
+      {
+        $set: {
+          code: outcome.code ?? null,
+          expiresAt: new Date(now.getTime() + this.options.retentionMs),
+          state: 'done',
+          status: outcome.status,
+          version: outcome.version ?? null,
+        },
+      },
+    );
+  }
+
+  /** Give up a claim whose write did not happen (a transient failure), so the client's retry is written anew */
+  async release(key: string): Promise<void> {
+    await this.store.deleteOne({ key, state: 'pending' });
+  }
+
+  protected pending(now: Date, attempt: number): Omit<MutationRecord, 'key'> {
+    return {
+      attempt,
+      claimedAt: now,
+      code: null,
+      expiresAt: new Date(now.getTime() + this.options.retentionMs),
+      state: 'pending',
+      status: null,
+      version: null,
+    };
+  }
+
+  /** Take an abandoned or expired entry over: conditional on the attempt the reader saw, so one contender wins */
+  protected async takeOver(existing: StoredRecord<MutationRecord>, now: Date): Promise<boolean> {
+    const attempt = existing.attempt ?? 0;
+    const taken = await this.store.updateOne(
+      { attempt: existing.attempt ?? null, id: existing.id },
+      { $set: this.pending(now, attempt + 1) },
+    );
+    return !!taken;
+  }
+}
+
+function isExpired(record: MutationRecord, now: Date): boolean {
+  return !!record.expiresAt && new Date(record.expiresAt).getTime() <= now.getTime();
+}
+
+function outcomeOf(record: MutationRecord): SyncMutationOutcome {
+  return {
+    ...(record.code ? { code: record.code } : {}),
+    status: record.status,
+    ...(typeof record.version === 'number' ? { version: record.version } : {}),
+  };
+}
+
+/** A unique index refused the write — MongoDB's code, which the SQL stores carry too (`DuplicateKeyError`) */
+export function isDuplicateKey(error: unknown): boolean {
+  return (error as { code?: unknown })?.code === 11000;
+}