@delali/sirannon-db 0.3.5 → 0.3.6-next.78

package/dist/server/index.mjs

@@ -1,22 +1,24 @@
-import { restoreBackup, MAX_RESTORE_BATCH_SIZE } from '../chunk-L6EX6K27.mjs';
-import { tablesInFkOrder, dumpSchema, dumpTablePages } from '../chunk-DKML5425.mjs';
-import { resolveDeviceRetentionPolicy, ChangeTracker, SubscriptionManager, ensureCdcEpoch, migrationChecksum, applyDeviceCursorBoundary, needsResync, filteredChange, TransactionGrouper, isBulkLoadDurability, PrimedSubscription } from '../chunk-SB3MIFLG.mjs';
-import '../chunk-YW7IKQ7T.mjs';
-import { SEQ_STRING_RE, highestMigrationVersion, selectCountTableRows, selectTableExists, selectAppliedMigrations, PkResolver, ensureDeviceCursorsTable, upsertDeviceCursor, updateDeviceCursor, selectMaxAssignedChangeSeq, MAX_CHANGE_SEQ, HLC, selectMaxChangeSeq, canonicaliseForChecksum, selectDeviceCursorExists, IDENTIFIER_RE } from '../chunk-RPWBYASV.mjs';
+import { restoreBackup, MAX_RESTORE_BATCH_SIZE } from '../chunk-MO4APBYG.mjs';
+import { tablesInFkOrder, dumpSchema, dumpTablePages } from '../chunk-GBVB6WSC.mjs';
+import { resolveDeviceRetentionPolicy, ChangeTracker, SubscriptionManager, ensureCdcEpoch, migrationChecksum, needsResync, filteredChange, TransactionGrouper, isBulkLoadDurability, PrimedSubscription, applyDeviceCursorBoundary } from '../chunk-2ZQOZFX7.mjs';
+import { wipeEncryptionKey, resolveEncryptionKey } from '../chunk-W74HFQFD.mjs';
+import { SEQ_STRING_RE, highestMigrationVersion, selectCountTableRows, selectTableExists, selectAppliedMigrations, PkResolver, ensureDeviceCursorsTable, upsertDeviceCursor, updateDeviceCursor, selectMaxAssignedChangeSeq, MAX_CHANGE_SEQ, HLC, selectMaxChangeSeq, canonicaliseForChecksum, selectDeviceCursorExists, IDENTIFIER_RE } from '../chunk-MTOQ6QIS.mjs';
+import { object, nullable, pipe, string, minLength, maxLength, safeParse } from '../chunk-5DKWHT6K.mjs';
 import { BatchValidationError } from '../chunk-BLMRNSUG.mjs';
-import { MIGRATIONS_TABLE, decodeTaggedValues, encodeTaggedValues, encodeWireRowsInPlace, DEVICE_CURSORS_TABLE, CHANGES_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-JFVEGN7J.mjs';
+import { MIGRATIONS_TABLE, decodeTaggedValues, encodeTaggedValues, encodeWireRowsInPlace, DEVICE_CURSORS_TABLE, CHANGES_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-ZAUHAJ4G.mjs';
 import { createOperationSource, operationRegistryDigest, findRead, isRefusal, resolveArguments, findWrite } from '../chunk-KB4OLJAD.mjs';
 import '../chunk-SEL4A4WT.mjs';
 import '../chunk-GVCNMPOS.mjs';
 import { optionalDependencyError } from '../chunk-WOMADPM4.mjs';
-import { discardStagedChain } from '../chunk-UHUDPQFI.mjs';
+import { discardStagedChain } from '../chunk-OJXV4L3N.mjs';
 import '../chunk-QGVRRKB2.mjs';
 import '../chunk-AHCMO4YL.mjs';
 import '../chunk-BUWJH3D3.mjs';
-import '../chunk-YCMB6GR4.mjs';
-import '../chunk-CZL4D3BM.mjs';
+import '../chunk-6CABU54O.mjs';
 import '../chunk-BGJ5JVYL.mjs';
 import '../chunk-HO2XTXVX.mjs';
+import '../chunk-YCMB6GR4.mjs';
+import '../chunk-5O4J6LQQ.mjs';
 import { SQLITE_USER_VERSION_MAX } from '../chunk-BZWDPF4G.mjs';
 import { SirannonError, WriteOverloadError } from '../chunk-KINDFBQP.mjs';
 import { createHash } from 'crypto';
@@ -152,10 +154,23 @@ var SERVER_FAULT_MESSAGES = /* @__PURE__ */ new Map([
   ],
   ["SERVER_DEPENDENCY_MISSING", OPTIONAL_PACKAGE_MISSING],
   ["TRANSPORT_DEPENDENCY_MISSING", OPTIONAL_PACKAGE_MISSING],
-  ["COORDINATOR_DEPENDENCY_MISSING", OPTIONAL_PACKAGE_MISSING]
+  ["COORDINATOR_DEPENDENCY_MISSING", OPTIONAL_PACKAGE_MISSING],
+  ["ENCRYPTION_UNSUPPORTED", "The server's SQLite driver cannot encrypt a database"],
+  ["INVALID_ENCRYPTION_KEY", "The encryption key for this database is not a 32-byte key"],
+  ["ENCRYPTION_KEY_UNAVAILABLE", "The server could not obtain the encryption key for this database"],
+  ["ENCRYPTION_KEY_MISSING", "This database is encrypted, and the server opened it without a key"],
+  ["ENCRYPTION_KEY_REJECTED", "The key that the server holds does not open this database"],
+  ["DATABASE_NOT_ENCRYPTED", "This database is not encrypted, and the server opened it with a key"],
+  ["ENCRYPTED_PAGE_CORRUPT", "A page of this encrypted database failed its integrity check"],
+  ["ENCRYPTION_REQUIRED", "An encrypted node sends no data to a node that holds a plaintext database"],
+  ["ENCRYPTION_CHANGE_IN_PROGRESS", "A key change is running on this database"],
+  ["ENCRYPTION_CHANGE_ABORTED", "The key change stopped and left the database under its current key"]
 ]);
 function clientErrorMessage(err) {
-  return SERVER_FAULT_MESSAGES.get(err.code) ?? err.message;
+  return clientMessageFor(err);
+}
+function clientMessageFor(error) {
+  return SERVER_FAULT_MESSAGES.get(error.code) ?? error.message;
 }
 function sharesErrorDetails(err) {
   return !SERVER_FAULT_MESSAGES.has(err.code);
@@ -477,8 +492,12 @@ function httpStatusForError(err) {
     case "HOOK_DENIED":
       return 403;
     case "BACKUP_CHAIN_BROKEN":
+    case "REPLICATION_ACTIVE":
+    case "ENCRYPTION_CHANGE_IN_PROGRESS":
+    case "ENCRYPTION_REQUIRED":
       return 409;
     case "BACKUP_UNSUPPORTED":
+    case "ENCRYPTION_UNSUPPORTED":
       return 501;
     case "BACKUP_DESTINATION_ERROR":
       return 502;
@@ -492,6 +511,7 @@ function httpStatusForError(err) {
     case "NODE_DRAINING":
     case "UNSAFE_RECOVERY_REQUIRED":
     case "WRITE_OVERLOADED":
+    case "ENCRYPTION_KEY_UNAVAILABLE":
       return 503;
     default:
       return 500;
@@ -1158,232 +1178,6 @@ function readinessStatusForReplication(replication, current) {
   return current;
 }
 
-// src/server/backup-protocol.ts
-var BACKUP_RESTORE_NOT_ACCEPTED_MESSAGE = "This server does not restore databases over the wire; turn on acceptBackupRestore to open the route";
-function wholeNumberError(field, value, atLeast, atMost) {
-  if (value === void 0) return null;
-  if (typeof value !== "number" || !Number.isInteger(value) || value < atLeast) {
-    return `Field "${field}" must be a whole number of at least ${atLeast}`;
-  }
-  if (atMost !== void 0 && value > atMost) {
-    return `Field "${field}" must be a whole number of at most ${atMost}`;
-  }
-  return null;
-}
-function verifyNameValidationError(value) {
-  if (typeof value !== "string" || value.length === 0) {
-    return 'Field "name" is required and must be the name a chain record states';
-  }
-  return null;
-}
-function restorableFromValidationError(value) {
-  return wholeNumberError("restorableFrom", value, 0);
-}
-function restoreRequestValidationError(body) {
-  return wholeNumberError("moment", body.moment, 0) ?? wholeNumberError("batchSize", body.batchSize, 1, MAX_RESTORE_BATCH_SIZE);
-}
-
-// src/server/http-backups.ts
-function parseOptionalBody(res, rawBody) {
-  if (rawBody.length === 0) return {};
-  return parseBody(res, rawBody);
-}
-async function resolveBackupDatabase(res, abort, sirannon, dbId) {
-  let database;
-  try {
-    database = await sirannon.resolve(dbId);
-  } catch (err) {
-    sendCaughtError(res, abort, err);
-    return null;
-  }
-  if (abort.aborted) return null;
-  if (!database) {
-    sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
-    return null;
-  }
-  return database;
-}
-function refusedOnTheFirstTick(turn) {
-  const settled = turn.then(
-    () => void 0,
-    (err) => err ?? new SirannonError("The backup turn failed", "BACKUP_ERROR")
-  );
-  const tick = new Promise((resolve) => {
-    setImmediate(() => resolve(void 0));
-  });
-  return Promise.race([settled, tick]);
-}
-function readStatus(res, abort, database) {
-  try {
-    return database.backupStatus();
-  } catch (err) {
-    sendCaughtError(res, abort, err);
-    return null;
-  }
-}
-function handleBackupTrigger(sirannon) {
-  return async (res, dbId, rawBody, abort) => {
-    if (!parseOptionalBody(res, rawBody)) return;
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    if (!readStatus(res, abort, database)) return;
-    const refusal = await refusedOnTheFirstTick(database.captureBackupChanges());
-    if (refusal !== void 0) {
-      sendCaughtError(res, abort, refusal);
-      return;
-    }
-    if (abort.aborted) return;
-    sendJson(res, { started: true }, "202 Accepted");
-  };
-}
-function handleBackupStatus(sirannon) {
-  return async (res, dbId, _ctx, abort) => {
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    const status = readStatus(res, abort, database);
-    if (!status || abort.aborted) return;
-    sendJson(res, status);
-  };
-}
-function handleBackupChain(sirannon) {
-  return async (res, dbId, _ctx, abort) => {
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    try {
-      const chains = await database.backupChain();
-      if (abort.aborted) return;
-      const body = { chains };
-      sendJson(res, body);
-    } catch (err) {
-      sendCaughtError(res, abort, err);
-    }
-  };
-}
-function handleBackupVerify(sirannon) {
-  return async (res, dbId, rawBody, abort) => {
-    const body = parseOptionalBody(res, rawBody);
-    if (!body) return;
-    const name = body.name;
-    const nameError = verifyNameValidationError(name);
-    if (nameError !== null || typeof name !== "string") {
-      sendError(res, 400, "INVALID_REQUEST", nameError ?? 'Field "name" must be a string');
-      return;
-    }
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    try {
-      const result = await database.verifyBackup(name);
-      if (abort.aborted) return;
-      sendJson(res, result);
-    } catch (err) {
-      sendCaughtError(res, abort, err);
-    }
-  };
-}
-function handleBackupSafeToDelete(sirannon) {
-  return async (res, dbId, rawBody, abort) => {
-    const body = parseOptionalBody(res, rawBody);
-    if (!body) return;
-    const restorableFromError = restorableFromValidationError(body.restorableFrom);
-    if (restorableFromError !== null) {
-      sendError(res, 400, "INVALID_REQUEST", restorableFromError);
-      return;
-    }
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    try {
-      const records = await database.backupPiecesSafeToDelete(
-        body.restorableFrom === void 0 ? void 0 : { restorableFrom: body.restorableFrom }
-      );
-      if (abort.aborted) return;
-      const answer = { records };
-      sendJson(res, answer);
-    } catch (err) {
-      sendCaughtError(res, abort, err);
-    }
-  };
-}
-
-// src/server/http-backup-restore.ts
-function restoreAlreadyRunning(databaseId) {
-  return `A restore of database '${databaseId}' is already under way, and it keeps that file to itself until it finishes`;
-}
-async function rebuildDatabase(request) {
-  const { sirannon, runs, databaseId, location } = request;
-  try {
-    const outcome = await sirannon.withDatabaseOffline(databaseId, async (destPath) => {
-      await discardStagedChain(location.stagingDir);
-      return restoreBackup({
-        destination: location.destination,
-        chainName: location.chainName,
-        driver: sirannon.driver,
-        destPath,
-        replaceExisting: true,
-        moment: request.moment,
-        ...location.destinationTimeoutMs === void 0 ? {} : { destinationTimeoutMs: location.destinationTimeoutMs },
-        ...request.batchSize === void 0 ? {} : { batchSize: request.batchSize },
-        onProgress: (progress) => runs.progressed(databaseId, progress)
-      });
-    });
-    if (!outcome.ok) {
-      runs.failed(databaseId, outcome.failure);
-      return;
-    }
-    runs.finished(databaseId, outcome.value, outcome.reopenFailure);
-  } catch (err) {
-    runs.failed(databaseId, err);
-  }
-}
-function handleBackupRestore(sirannon, accepted, runs) {
-  return async (res, dbId, rawBody, abort) => {
-    if (!accepted) {
-      sendError(res, 403, "BACKUP_RESTORE_NOT_ACCEPTED", BACKUP_RESTORE_NOT_ACCEPTED_MESSAGE);
-      return;
-    }
-    const body = parseOptionalBody(res, rawBody);
-    if (!body) return;
-    const validationError = restoreRequestValidationError(body);
-    if (validationError !== null) {
-      sendError(res, 400, "INVALID_REQUEST", validationError);
-      return;
-    }
-    if (runs.read(dbId).state === "running") {
-      sendError(res, 409, "BACKUP_RESTORE_IN_PROGRESS", restoreAlreadyRunning(dbId));
-      return;
-    }
-    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
-    if (!database) return;
-    let location;
-    try {
-      location = database.backupLocation();
-    } catch (err) {
-      sendCaughtError(res, abort, err);
-      return;
-    }
-    const moment = body.moment === void 0 ? Date.now() : body.moment;
-    if (!runs.claim(dbId, moment)) {
-      sendError(res, 409, "BACKUP_RESTORE_IN_PROGRESS", restoreAlreadyRunning(dbId));
-      return;
-    }
-    void rebuildDatabase({
-      sirannon,
-      runs,
-      databaseId: dbId,
-      location,
-      moment,
-      ...body.batchSize === void 0 ? {} : { batchSize: body.batchSize }
-    });
-    if (abort.aborted) return;
-    sendJson(res, { started: true }, "202 Accepted");
-  };
-}
-function handleBackupRestoreStatus(runs) {
-  return async (res, dbId, _ctx, abort) => {
-    if (abort.aborted) return;
-    sendJson(res, runs.read(dbId));
-  };
-}
-
 // src/server/sync-protocol.ts
 var MAX_SYNC_BATCH_CHANGES = 1e3;
 var NODE_ID_RE = /^[0-9a-f]{32}$/;
@@ -1547,111 +1341,351 @@ function decodeSyncBatch(body) {
 function toChangesResponse(result) {
   return { applied: result.applied, skipped: result.skipped, conflicts: result.conflicts };
 }
-
-// src/server/http-changes.ts
-var MAX_DEVICE_CLOCK_AHEAD_MS = 3e5;
-function changeClockRefusal(batch, nowMs) {
-  for (const [index, change] of batch.changes.entries()) {
-    let wallMs;
+
+// src/server/http-changes.ts
+var MAX_DEVICE_CLOCK_AHEAD_MS = 3e5;
+function changeClockRefusal(batch, nowMs) {
+  for (const [index, change] of batch.changes.entries()) {
+    let wallMs;
+    try {
+      wallMs = HLC.decode(change.hlc).wallMs;
+    } catch {
+      wallMs = Number.NaN;
+    }
+    if (!Number.isFinite(wallMs)) {
+      return { code: "INVALID_REQUEST", message: `changes[${index}].hlc is not a valid timestamp` };
+    }
+    if (wallMs > nowMs + MAX_DEVICE_CLOCK_AHEAD_MS) {
+      return {
+        code: "DEVICE_CLOCK_AHEAD",
+        message: `changes[${index}] is stamped more than ${MAX_DEVICE_CLOCK_AHEAD_MS} ms ahead of the server clock; correct the device clock`
+      };
+    }
+  }
+  return null;
+}
+function clockRangeOf(changes) {
+  let min = changes[0].hlc;
+  let max = changes[0].hlc;
+  for (const change of changes) {
+    if (change.hlc < min) min = change.hlc;
+    if (change.hlc > max) max = change.hlc;
+  }
+  return { min, max };
+}
+function decodeVerifiableBatch(body) {
+  let decoded;
+  try {
+    decoded = decodeSyncBatch(body);
+  } catch {
+    return null;
+  }
+  return { ...decoded, hlcRange: clockRangeOf(decoded.changes) };
+}
+async function refuseUngrantedPush(sirannon, databaseId, batch, identity) {
+  if (!sirannon.hookRegistry.has("beforePush")) return;
+  const tables = new Set(batch.changes.map((change) => change.table));
+  for (const table of tables) {
+    const ctx = { databaseId, table, deviceId: batch.sourceNodeId, identity };
+    await sirannon.hookRegistry.invoke("beforePush", ctx);
+  }
+}
+async function refuseSchemaMismatch(res, abort, target, deviceVersion) {
+  const appliedMigrations = target.appliedMigrations;
+  if (typeof appliedMigrations !== "function") return false;
+  const serverVersion = highestMigrationVersion(await appliedMigrations.call(target));
+  const refusal = schemaVersionGateRefusal(deviceVersion, serverVersion);
+  if (refusal === null) return false;
+  if (!abort.aborted) {
+    sendError(res, 409, refusal.code, refusal.message, { serverVersion });
+  }
+  return true;
+}
+function handleChanges(sirannon, resolveTarget) {
+  return async (res, dbId, rawBody, abort, identity) => {
+    const body = parseBody(res, rawBody);
+    if (!body) return;
+    const batchError = syncBatchValidationError(body.batch);
+    if (batchError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", batchError);
+      return;
+    }
+    const schemaVersionError = schemaVersionValidationError(body.schemaVersion);
+    if (schemaVersionError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", schemaVersionError);
+      return;
+    }
+    const batch = decodeVerifiableBatch(body.batch);
+    if (batch === null) {
+      sendError(res, 400, "INVALID_REQUEST", '"batch.changes" carries a malformed tagged value');
+      return;
+    }
+    const target = await resolveExecutionTarget(res, abort, sirannon, dbId, resolveTarget);
+    if (!target) return;
+    try {
+      await refuseUngrantedPush(sirannon, dbId, batch, identity);
+      const clockRefusal = changeClockRefusal(batch, Date.now());
+      if (clockRefusal !== null) {
+        sendError(res, 400, clockRefusal.code, clockRefusal.message);
+        return;
+      }
+      if (await refuseSchemaMismatch(res, abort, target, body.schemaVersion ?? 0)) return;
+      const applyChanges = target.applyChanges;
+      if (typeof applyChanges !== "function") {
+        sendError(
+          res,
+          501,
+          "SYNC_UNSUPPORTED",
+          "The execution target for this database does not support applying sync changes"
+        );
+        return;
+      }
+      const result = await applyChanges.call(target, batch);
+      if (abort.aborted) return;
+      sendJson(res, toChangesResponse(result));
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+
+// src/server/backup-protocol.ts
+var BACKUP_RESTORE_NOT_ACCEPTED_MESSAGE = "This server does not restore databases over the wire; turn on acceptBackupRestore to open the route";
+function wholeNumberError(field, value, atLeast, atMost) {
+  if (value === void 0) return null;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < atLeast) {
+    return `Field "${field}" must be a whole number of at least ${atLeast}`;
+  }
+  if (atMost !== void 0 && value > atMost) {
+    return `Field "${field}" must be a whole number of at most ${atMost}`;
+  }
+  return null;
+}
+function verifyNameValidationError(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return 'Field "name" is required and must be the name a chain record states';
+  }
+  return null;
+}
+function restorableFromValidationError(value) {
+  return wholeNumberError("restorableFrom", value, 0);
+}
+function restoreRequestValidationError(body) {
+  return wholeNumberError("moment", body.moment, 0) ?? wholeNumberError("batchSize", body.batchSize, 1, MAX_RESTORE_BATCH_SIZE);
+}
+
+// src/server/http-backups.ts
+function parseOptionalBody(res, rawBody) {
+  if (rawBody.length === 0) return {};
+  return parseBody(res, rawBody);
+}
+async function resolveBackupDatabase(res, abort, sirannon, dbId) {
+  let database;
+  try {
+    database = await sirannon.resolve(dbId);
+  } catch (err) {
+    sendCaughtError(res, abort, err);
+    return null;
+  }
+  if (abort.aborted) return null;
+  if (!database) {
+    sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
+    return null;
+  }
+  return database;
+}
+function refusedOnTheFirstTick(turn) {
+  const settled = turn.then(
+    () => void 0,
+    (err) => err ?? new SirannonError("The backup turn failed", "BACKUP_ERROR")
+  );
+  const tick = new Promise((resolve) => {
+    setImmediate(() => resolve(void 0));
+  });
+  return Promise.race([settled, tick]);
+}
+function readStatus(res, abort, database) {
+  try {
+    return database.backupStatus();
+  } catch (err) {
+    sendCaughtError(res, abort, err);
+    return null;
+  }
+}
+function handleBackupTrigger(sirannon) {
+  return async (res, dbId, rawBody, abort) => {
+    if (!parseOptionalBody(res, rawBody)) return;
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    if (!readStatus(res, abort, database)) return;
+    const refusal = await refusedOnTheFirstTick(database.captureBackupChanges());
+    if (refusal !== void 0) {
+      sendCaughtError(res, abort, refusal);
+      return;
+    }
+    if (abort.aborted) return;
+    sendJson(res, { started: true }, "202 Accepted");
+  };
+}
+function handleBackupStatus(sirannon) {
+  return async (res, dbId, _ctx, abort) => {
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    const status = readStatus(res, abort, database);
+    if (!status || abort.aborted) return;
+    sendJson(res, status);
+  };
+}
+function handleBackupChain(sirannon) {
+  return async (res, dbId, _ctx, abort) => {
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    try {
+      const chains = await database.backupChain();
+      if (abort.aborted) return;
+      const body = { chains };
+      sendJson(res, body);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+    }
+  };
+}
+function handleBackupVerify(sirannon) {
+  return async (res, dbId, rawBody, abort) => {
+    const body = parseOptionalBody(res, rawBody);
+    if (!body) return;
+    const name = body.name;
+    const nameError = verifyNameValidationError(name);
+    if (nameError !== null || typeof name !== "string") {
+      sendError(res, 400, "INVALID_REQUEST", nameError ?? 'Field "name" must be a string');
+      return;
+    }
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
     try {
-      wallMs = HLC.decode(change.hlc).wallMs;
-    } catch {
-      wallMs = Number.NaN;
+      const result = await database.verifyBackup(name);
+      if (abort.aborted) return;
+      sendJson(res, result);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
     }
-    if (!Number.isFinite(wallMs)) {
-      return { code: "INVALID_REQUEST", message: `changes[${index}].hlc is not a valid timestamp` };
+  };
+}
+function handleBackupSafeToDelete(sirannon) {
+  return async (res, dbId, rawBody, abort) => {
+    const body = parseOptionalBody(res, rawBody);
+    if (!body) return;
+    const restorableFromError = restorableFromValidationError(body.restorableFrom);
+    if (restorableFromError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", restorableFromError);
+      return;
     }
-    if (wallMs > nowMs + MAX_DEVICE_CLOCK_AHEAD_MS) {
-      return {
-        code: "DEVICE_CLOCK_AHEAD",
-        message: `changes[${index}] is stamped more than ${MAX_DEVICE_CLOCK_AHEAD_MS} ms ahead of the server clock; correct the device clock`
-      };
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    try {
+      const records = await database.backupPiecesSafeToDelete(
+        body.restorableFrom === void 0 ? void 0 : { restorableFrom: body.restorableFrom }
+      );
+      if (abort.aborted) return;
+      const answer = { records };
+      sendJson(res, answer);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
     }
-  }
-  return null;
+  };
 }
-function clockRangeOf(changes) {
-  let min = changes[0].hlc;
-  let max = changes[0].hlc;
-  for (const change of changes) {
-    if (change.hlc < min) min = change.hlc;
-    if (change.hlc > max) max = change.hlc;
+
+// src/server/http-encryption.ts
+var MAX_KEY_REF_LENGTH = 256;
+var ENCRYPTION_CHANGE_REQUEST = object({
+  keyRef: nullable(pipe(string(), minLength(1), maxLength(MAX_KEY_REF_LENGTH)))
+});
+var ENCRYPTION_CHANGE_NOT_ACCEPTED_MESSAGE = "This server does not change database keys over the wire; turn on acceptEncryptionChange to open the route";
+function resolveEncryptionChangeSettings(options) {
+  const accepted = options?.acceptEncryptionChange === true;
+  if (accepted && (options?.authenticate === void 0 || typeof options.encryptionKeys !== "function")) {
+    throw new SirannonError(
+      "ServerOptions.acceptEncryptionChange opens a route that changes the key of a running database, so it needs an authenticate hook to name the caller and an encryptionKeys function to resolve each keyRef",
+      "INVALID_ENCRYPTION_CHANGE"
+    );
   }
-  return { min, max };
+  return { accepted, keys: options?.encryptionKeys };
 }
-function decodeVerifiableBatch(body) {
-  let decoded;
-  try {
-    decoded = decodeSyncBatch(body);
-  } catch {
-    return null;
-  }
-  return { ...decoded, hlcRange: clockRangeOf(decoded.changes) };
+async function checkedKeySource(keys, databaseId, keyRef) {
+  const source = () => keys(databaseId, keyRef);
+  wipeEncryptionKey(await resolveEncryptionKey(source));
+  return source;
 }
-async function refuseUngrantedPush(sirannon, databaseId, batch, identity) {
-  if (!sirannon.hookRegistry.has("beforePush")) return;
-  const tables = new Set(batch.changes.map((change) => change.table));
-  for (const table of tables) {
-    const ctx = { databaseId, table, deviceId: batch.sourceNodeId, identity };
-    await sirannon.hookRegistry.invoke("beforePush", ctx);
-  }
+function errorForClient(error) {
+  return { code: error.code, message: clientMessageFor(error) };
 }
-async function refuseSchemaMismatch(res, abort, target, deviceVersion) {
-  const appliedMigrations = target.appliedMigrations;
-  if (typeof appliedMigrations !== "function") return false;
-  const serverVersion = highestMigrationVersion(await appliedMigrations.call(target));
-  const refusal = schemaVersionGateRefusal(deviceVersion, serverVersion);
-  if (refusal === null) return false;
-  if (!abort.aborted) {
-    sendError(res, 409, refusal.code, refusal.message, { serverVersion });
-  }
-  return true;
+function statusForClient(status) {
+  const { error, reopenError } = status.change;
+  return {
+    ...status,
+    change: {
+      ...status.change,
+      ...error === void 0 ? {} : { error: errorForClient(error) },
+      ...reopenError === void 0 ? {} : { reopenError: errorForClient(reopenError) }
+    }
+  };
 }
-function handleChanges(sirannon, resolveTarget) {
-  return async (res, dbId, rawBody, abort, identity) => {
-    const body = parseBody(res, rawBody);
-    if (!body) return;
-    const batchError = syncBatchValidationError(body.batch);
-    if (batchError !== null) {
-      sendError(res, 400, "INVALID_REQUEST", batchError);
+function handleEncryptionChange(sirannon, settings) {
+  return async (res, dbId, rawBody, abort) => {
+    const keys = settings.keys;
+    if (!settings.accepted || keys === void 0) {
+      sendError(res, 403, "ENCRYPTION_CHANGE_NOT_ACCEPTED", ENCRYPTION_CHANGE_NOT_ACCEPTED_MESSAGE);
       return;
     }
-    const schemaVersionError = schemaVersionValidationError(body.schemaVersion);
-    if (schemaVersionError !== null) {
-      sendError(res, 400, "INVALID_REQUEST", schemaVersionError);
+    const body = parseOptionalBody(res, rawBody);
+    if (body === null) return;
+    const request = safeParse(ENCRYPTION_CHANGE_REQUEST, body);
+    if (!request.success) {
+      sendError(
+        res,
+        400,
+        "INVALID_REQUEST",
+        `keyRef takes a string of 1 to ${MAX_KEY_REF_LENGTH} characters that names the target key, or null to remove encryption`
+      );
       return;
     }
-    const batch = decodeVerifiableBatch(body.batch);
-    if (batch === null) {
-      sendError(res, 400, "INVALID_REQUEST", '"batch.changes" carries a malformed tagged value');
+    const database = sirannon.get(dbId);
+    if (!database) {
+      sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
       return;
     }
-    const target = await resolveExecutionTarget(res, abort, sirannon, dbId, resolveTarget);
-    if (!target) return;
+    let key = null;
     try {
-      await refuseUngrantedPush(sirannon, dbId, batch, identity);
-      const clockRefusal = changeClockRefusal(batch, Date.now());
-      if (clockRefusal !== null) {
-        sendError(res, 400, clockRefusal.code, clockRefusal.message);
-        return;
-      }
-      if (await refuseSchemaMismatch(res, abort, target, body.schemaVersion ?? 0)) return;
-      const applyChanges = target.applyChanges;
-      if (typeof applyChanges !== "function") {
-        sendError(
-          res,
-          501,
-          "SYNC_UNSUPPORTED",
-          "The execution target for this database does not support applying sync changes"
-        );
-        return;
-      }
-      const result = await applyChanges.call(target, batch);
-      if (abort.aborted) return;
-      sendJson(res, toChangesResponse(result));
+      if (request.output.keyRef !== null) key = await checkedKeySource(keys, dbId, request.output.keyRef);
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+      return;
+    }
+    const refusal = await refusedOnTheFirstTick(database.changeEncryption({ key }));
+    if (refusal !== void 0) {
+      sendCaughtError(res, abort, refusal);
+      return;
+    }
+    if (abort.aborted) return;
+    sendJson(res, { started: true }, "202 Accepted");
+  };
+}
+function handleEncryptionStatus(sirannon) {
+  return async (res, dbId, _ctx, abort) => {
+    const database = sirannon.get(dbId);
+    if (!database) {
+      sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${dbId}' not found`);
+      return;
+    }
+    let status;
+    try {
+      status = await database.encryptionStatus();
     } catch (err) {
       sendCaughtError(res, abort, err);
+      return;
     }
+    if (abort.aborted) return;
+    sendJson(res, statusForClient(status));
   };
 }
 
@@ -1880,7 +1914,7 @@ function handleSnapshotManifest(sirannon) {
       await database.runCdcMaintenance(async (writer) => {
         epoch = await ensureCdcEpoch(writer);
       });
-      const conn = await sirannon.driver.open(database.path, { walMode: true });
+      const conn = await database.openFileConnection({ walMode: true });
       try {
         const tableNames = await tablesInFkOrder(conn);
         await refuseUngrantedTables(sirannon, dbId, tableNames, identity);
@@ -1935,7 +1969,7 @@ function handleSnapshotPage(sirannon) {
     if (!database) return;
     try {
       await refuseUngrantedTables(sirannon, dbId, [body.table], identity);
-      const conn = await sirannon.driver.open(database.path, { walMode: true });
+      const conn = await database.openFileConnection({ walMode: true });
       try {
         if (!await selectTableExists(conn, body.table)) {
           sendError(res, 404, "TABLE_NOT_FOUND", `Table '${body.table}' not found`);
@@ -2116,6 +2150,104 @@ function wrapOperationRoute(deps, handler) {
   };
 }
 
+// src/server/http-backup-restore.ts
+function restoreAlreadyRunning(databaseId) {
+  return `A restore of database '${databaseId}' is already under way, and it keeps that file to itself until it finishes`;
+}
+async function rebuildDatabase(request) {
+  const { sirannon, runs, databaseId, location } = request;
+  try {
+    const outcome = await sirannon.withDatabaseOffline(databaseId, async (destPath, encryption) => {
+      await discardStagedChain(location.stagingDir);
+      return restoreBackup({
+        destination: location.destination,
+        chainName: location.chainName,
+        driver: sirannon.driver,
+        destPath,
+        ...encryption === void 0 ? {} : { encryption },
+        replaceExisting: true,
+        moment: request.moment,
+        ...location.destinationTimeoutMs === void 0 ? {} : { destinationTimeoutMs: location.destinationTimeoutMs },
+        ...request.batchSize === void 0 ? {} : { batchSize: request.batchSize },
+        onProgress: (progress) => runs.progressed(databaseId, progress)
+      });
+    });
+    if (!outcome.ok) {
+      runs.failed(databaseId, outcome.failure);
+      return;
+    }
+    runs.finished(databaseId, outcome.value, outcome.reopenFailure);
+  } catch (err) {
+    runs.failed(databaseId, err);
+  }
+}
+function handleBackupRestore(sirannon, accepted, runs) {
+  return async (res, dbId, rawBody, abort) => {
+    if (!accepted) {
+      sendError(res, 403, "BACKUP_RESTORE_NOT_ACCEPTED", BACKUP_RESTORE_NOT_ACCEPTED_MESSAGE);
+      return;
+    }
+    const body = parseOptionalBody(res, rawBody);
+    if (!body) return;
+    const validationError = restoreRequestValidationError(body);
+    if (validationError !== null) {
+      sendError(res, 400, "INVALID_REQUEST", validationError);
+      return;
+    }
+    if (runs.read(dbId).state === "running") {
+      sendError(res, 409, "BACKUP_RESTORE_IN_PROGRESS", restoreAlreadyRunning(dbId));
+      return;
+    }
+    const database = await resolveBackupDatabase(res, abort, sirannon, dbId);
+    if (!database) return;
+    let location;
+    try {
+      database.assertNoReplicationEngine("restore");
+      location = database.backupLocation();
+    } catch (err) {
+      sendCaughtError(res, abort, err);
+      return;
+    }
+    const moment = body.moment === void 0 ? Date.now() : body.moment;
+    if (!runs.claim(dbId, moment)) {
+      sendError(res, 409, "BACKUP_RESTORE_IN_PROGRESS", restoreAlreadyRunning(dbId));
+      return;
+    }
+    void rebuildDatabase({
+      sirannon,
+      runs,
+      databaseId: dbId,
+      location,
+      moment,
+      ...body.batchSize === void 0 ? {} : { batchSize: body.batchSize }
+    });
+    if (abort.aborted) return;
+    sendJson(res, { started: true }, "202 Accepted");
+  };
+}
+function handleBackupRestoreStatus(runs) {
+  return async (res, dbId, _ctx, abort) => {
+    if (abort.aborted) return;
+    sendJson(res, runs.read(dbId));
+  };
+}
+
+// src/server/operator-routes.ts
+function registerOperatorRoutes(routes, deps) {
+  const { sirannon, routeDeps } = deps;
+  const post = (path, handler) => routes.post(path, wrapDbRoute(routeDeps, handler));
+  const get = (path, handler) => routes.get(path, wrapDbGetRoute(routeDeps, handler));
+  post("/db/:id/backup", handleBackupTrigger(sirannon));
+  get("/db/:id/backup", handleBackupStatus(sirannon));
+  get("/db/:id/backup/chain", handleBackupChain(sirannon));
+  post("/db/:id/backup/verify", handleBackupVerify(sirannon));
+  post("/db/:id/backup/safe-to-delete", handleBackupSafeToDelete(sirannon));
+  post("/db/:id/backup/restore", handleBackupRestore(sirannon, deps.acceptBackupRestore, deps.restoreRuns));
+  get("/db/:id/backup/restore", handleBackupRestoreStatus(deps.restoreRuns));
+  post("/db/:id/encryption", handleEncryptionChange(sirannon, deps.encryptionChange));
+  get("/db/:id/encryption", handleEncryptionStatus(sirannon));
+}
+
 // src/server/uws-loader.ts
 var UWEBSOCKETS_DEPENDENCY = {
   packageName: "uWebSockets.js",
@@ -2229,6 +2361,7 @@ var CdcContextRegistry = class {
       const ctx = await promise;
       if (this.closed) {
         ctx.stopPolling();
+        ctx.releaseHold();
         await ctx.cdcConn.close().catch(() => {
         });
         throw new SirannonError("WebSocket handler is shut down", "HANDLER_CLOSED");
@@ -2246,6 +2379,7 @@ var CdcContextRegistry = class {
     const ctx = this.contexts.get(databaseId);
     if (!ctx || ctx.manager.size > 0) return;
     ctx.stopPolling();
+    ctx.releaseHold();
     ctx.cdcConn.close().catch(() => {
     });
     this.contexts.delete(databaseId);
@@ -2255,6 +2389,7 @@ var CdcContextRegistry = class {
     this.closed = true;
     for (const ctx of this.contexts.values()) {
       ctx.stopPolling();
+      ctx.releaseHold();
       try {
         await ctx.cdcConn.close();
       } catch {
@@ -2263,7 +2398,7 @@ var CdcContextRegistry = class {
     this.contexts.clear();
   }
   async createContext(database) {
-    const cdcConn = await this.sirannon.driver.open(database.path, { walMode: true });
+    const cdcConn = await database.openFileConnection({ walMode: true });
     const retention = database.changeRetention.cdcRetention ?? this.retentionMs;
     const deviceRetention = resolveDeviceRetentionPolicy(database.changeRetention, this.serverDeviceRetention);
     const tracker = new ChangeTracker(retention === void 0 ? void 0 : { retention });
@@ -2284,19 +2419,21 @@ var CdcContextRegistry = class {
       });
       throw new SirannonError(`Database '${database.id}' is closed`, "DATABASE_CLOSED");
     }
-    let polling = false;
+    const ctx = { cdcConn, tracker, manager, stopPolling: () => {
+    }, releaseHold: () => {
+    }, epoch };
+    let interval = null;
+    let inFlight = null;
     let consecutiveErrors = 0;
     let tickCount = 0;
     const MAX_CONSECUTIVE_ERRORS = 10;
     const stopPolling = () => {
-      clearInterval(interval);
+      if (interval !== null) clearInterval(interval);
+      interval = null;
     };
-    const tick = async () => {
-      if (manager.size === 0) return;
-      if (polling) return;
-      polling = true;
+    const pollOnce = async () => {
       try {
-        const events = await tracker.poll(cdcConn);
+        const events = await tracker.poll(ctx.cdcConn);
         if (events.length > 0) {
           manager.dispatch(events);
         }
@@ -2316,13 +2453,36 @@ var CdcContextRegistry = class {
         if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
           stopPolling();
         }
-      } finally {
-        polling = false;
       }
     };
-    const interval = setInterval(tick, DEFAULT_POLL_INTERVAL_MS);
-    interval.unref?.();
-    return { cdcConn, tracker, manager, stopPolling, epoch };
+    const tick = () => {
+      if (manager.size === 0 || inFlight !== null) return;
+      inFlight = pollOnce().finally(() => {
+        inFlight = null;
+      });
+    };
+    const startPolling = () => {
+      stopPolling();
+      consecutiveErrors = 0;
+      const started = setInterval(tick, DEFAULT_POLL_INTERVAL_MS);
+      started.unref?.();
+      interval = started;
+    };
+    ctx.stopPolling = stopPolling;
+    startPolling();
+    ctx.releaseHold = database.holdFileConnection({
+      release: async () => {
+        stopPolling();
+        await inFlight;
+        await ctx.cdcConn.close().catch(() => {
+        });
+      },
+      reopen: async () => {
+        ctx.cdcConn = await database.openFileConnection({ walMode: true });
+        startPolling();
+      }
+    });
+    return ctx;
   }
 };
 
@@ -4093,6 +4253,7 @@ var SirannonServer = class {
   authenticateHook;
   acceptSql;
   acceptBackupRestore;
+  encryptionChange;
   acceptDeviceSync;
   restoreRuns = new BackupRestoreRuns();
   drain = new ConnectionDrain();
@@ -4115,6 +4276,7 @@ var SirannonServer = class {
     this.acceptSql = options?.acceptSql === true;
     this.acceptBackupRestore = options?.acceptBackupRestore === true;
     assertBackupRestoreAuthenticated(this.acceptBackupRestore, this.authenticateHook !== void 0);
+    this.encryptionChange = resolveEncryptionChangeSettings(options);
     this.acceptDeviceSync = options?.acceptDeviceSync === true;
     assertDeviceSyncAuthenticated(this.acceptDeviceSync, this.authenticateHook !== void 0);
     this.operations = { registry: options?.operations, shared: options?.sharedOperations };
@@ -4268,7 +4430,13 @@ var SirannonServer = class {
       "/db/:id/execute/:name",
       this.wrapOperationRoute(handleOperationExecute(this.sirannon, this.operations, this.resolveExecutionTarget))
     );
-    this.registerBackupRoutes(routes);
+    registerOperatorRoutes(routes, {
+      sirannon: this.sirannon,
+      routeDeps: this.routeDeps(),
+      acceptBackupRestore: this.acceptBackupRestore,
+      restoreRuns: this.restoreRuns,
+      encryptionChange: this.encryptionChange
+    });
     if (this.acceptDeviceSync) {
       routes.post("/db/:id/changes", this.wrapDbRoute(handleChanges(this.sirannon, this.resolveExecutionTarget)));
       routes.post("/db/:id/migrations", this.wrapDbRoute(handleMigrationList(this.sirannon)));
@@ -4291,18 +4459,6 @@ var SirannonServer = class {
       sendError(res, 404, "NOT_FOUND", "Route not found");
     });
   }
-  registerBackupRoutes(routes) {
-    routes.post("/db/:id/backup", this.wrapDbRoute(handleBackupTrigger(this.sirannon)));
-    routes.get("/db/:id/backup", this.wrapDbGetRoute(handleBackupStatus(this.sirannon)));
-    routes.get("/db/:id/backup/chain", this.wrapDbGetRoute(handleBackupChain(this.sirannon)));
-    routes.post("/db/:id/backup/verify", this.wrapDbRoute(handleBackupVerify(this.sirannon)));
-    routes.post("/db/:id/backup/safe-to-delete", this.wrapDbRoute(handleBackupSafeToDelete(this.sirannon)));
-    routes.post(
-      "/db/:id/backup/restore",
-      this.wrapDbRoute(handleBackupRestore(this.sirannon, this.acceptBackupRestore, this.restoreRuns))
-    );
-    routes.get("/db/:id/backup/restore", this.wrapDbGetRoute(handleBackupRestoreStatus(this.restoreRuns)));
-  }
   withCors(handler) {
     if (!this.cors) return handler;
     const cors = this.cors;