@delali/sirannon-db 0.3.6-next.77 → 0.3.6-next.79

package/README.md

@@ -6,7 +6,7 @@
 [![types](https://img.shields.io/badge/types-TypeScript-blue)](https://www.npmjs.com/package/@delali/sirannon-db)
 [![license](https://img.shields.io/npm/l/@delali/sirannon-db)](https://github.com/assetcorp/sirannon-db/blob/main/LICENSE)
 
-Build a networked SQLite service with connection pooling, change data capture, live queries, migrations, backups, device sync, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, while a primary replicates its changes to other Sirannon nodes over gRPC.
+Build an encrypted, networked SQLite service with connection pooling, change data capture, live queries, migrations, backups, device sync, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, while a primary replicates its changes to other Sirannon nodes over gRPC.
 
 **Read the full documentation at [sirannon.sondelali.com/docs](https://sirannon.sondelali.com/docs).** Use this page to get started, and turn to the [guides](#documentation) for the detail. The benchmark harness that measures Sirannon against Postgres 17 is under [`benchmarks/server`](https://github.com/assetcorp/sirannon-db/tree/main/benchmarks/server), where a Node load generator drives both engines and a Python step joins their results. The write-up generator rewrites [BENCHMARKS.md](https://github.com/assetcorp/sirannon-db/blob/main/BENCHMARKS.md) from the latest committed run.
 
@@ -61,7 +61,9 @@ import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
 const sirannon = new Sirannon({ driver: betterSqlite3() })
 const db = await sirannon.open('app', './data/app.db')
 
-await db.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)')
+await db.execute(
+  'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT, active INTEGER NOT NULL DEFAULT 1)',
+)
 await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Ada', 'ada@example.com'])
 
 const users = await db.query<{ id: number; name: string }>('SELECT * FROM users')
@@ -79,11 +81,36 @@ const db = await sirannon.open('app', '/app.db', { walMode: false })
 
 On React Native, open the database the same way with `expoSqlite()`.
 
+### Encrypt a database
+
+On Node.js, install Sirannon's encrypting SQLite build beside the library:
+
+```bash
+pnpm add -E @delali/sirannon-db @delali/sirannon-sqlite
+```
+
+Create the better-sqlite3 driver with encryption enabled. Return 32 raw key bytes when Sirannon opens the database:
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { Sirannon } from '@delali/sirannon-db'
+import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
+
+const loadLedgerKey = async () => new Uint8Array(await readFile('/run/secrets/ledger-key'))
+
+const sirannon = new Sirannon({ driver: betterSqlite3({ encryption: true }) })
+const db = await sirannon.open('ledger', './data/ledger.db', {
+  encryption: { key: async () => ({ key: await loadLedgerKey(), id: 'ledger-2026-11' }) },
+})
+```
+
+Store the key in a key service, a system keychain, or a secret file whose permissions restrict access to the application's operating-system account. Retain both keys until a key change finishes. Retain each backup chain's key for as long as you keep that chain. The [encryption guide](https://github.com/assetcorp/sirannon-db/blob/main/docs/encryption.md) covers key changes, encrypted backups, server routes, and Expo's SQLCipher setup.
+
 ## Package exports
 
 | Import | What you get |
 | --- | --- |
-| `@delali/sirannon-db` | Core library: queries, transactions, CDC, live queries, migrations, backups, hooks, metrics, and lifecycle |
+| `@delali/sirannon-db` | Core library: queries, transactions, encryption, CDC, live queries, migrations, backups, hooks, metrics, and lifecycle |
 | `@delali/sirannon-db/driver/*` | SQLite driver adapters, listed in the table above |
 | `@delali/sirannon-db/file-migrations` | A loader for `.up.sql` and `.down.sql` files in a directory |
 | `@delali/sirannon-db/backup` | Backup destination types, chain records, and `restoreBackup` |
@@ -252,6 +279,7 @@ Read the [security guide](https://sirannon.sondelali.com/docs/security) for each
 | [Bulk load](https://sirannon.sondelali.com/docs/bulk-load) | One-transaction imports under relaxed durability, over the server, and through the client SDK |
 | [Migrations](https://sirannon.sondelali.com/docs/migrations) | File-based, programmatic, and bundled migrations, rollback, checksums, baselines, concurrency, and registry migrations |
 | [Hooks, metrics, and lifecycle](https://sirannon.sondelali.com/docs/hooks-metrics-and-lifecycle) | Before and after hooks, metrics callbacks, and the multi-tenant lifecycle |
+| [Encryption](https://github.com/assetcorp/sirannon-db/blob/main/docs/encryption.md) | Encrypted Node and Expo databases, key changes, encrypted backups, and operator routes |
 | [Backups](https://sirannon.sondelali.com/docs/backups) | Copies of an open database to a file and on a schedule, followed by the guides on [destinations](https://sirannon.sondelali.com/docs/backup-destinations), [continuous backups](https://sirannon.sondelali.com/docs/backup-chains), and [restores](https://sirannon.sondelali.com/docs/backup-restore) |
 | [Server](https://sirannon.sondelali.com/docs/server) | Registered operations on the server, caller identity, size limits, write shapes, `acceptSql`, the backup routes, HTTP routes, and the WebSocket protocol |
 | [Registered operations](https://sirannon.sondelali.com/docs/registered-operations) | Named reads and writes, identity-filled arguments, calls over HTTP and WebSocket, capabilities, and refusals |

package/dist/backup/index.d.ts

@@ -1,8 +1,8 @@
-import { B as BackupDestination, g as BackupRunReport } from '../types-DTmi7pXp.js';
-export { h as BackupChain, i as BackupChainBase, j as BackupChainChange, k as BackupChainPosition, l as BackupChainRecord, m as BackupCycle, n as BackupCycleError, o as BackupCycleOptions, p as BackupCycleStatus, q as BackupFileReport, r as BackupGroupMembership, s as BackupGroupSource, t as BackupLogPosition, u as BackupNodePreference, v as BackupPiece, w as BackupProgress, x as BackupSkip, y as BackupSkipReason, z as BackupToDestinationOptions, C as BackupVerifyResult, E as DEFAULT_CHAIN_NAME, F as chainLogName, G as readBackupChains, H as verifyBackupRecord } from '../types-DTmi7pXp.js';
-export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-BwTNiBm2.js';
-import { B as BackupRestoreOptions, a as BackupRestoreReport } from '../restore-options-CcMukOLO.js';
-export { b as BackupRestoreProgress } from '../restore-options-CcMukOLO.js';
+import { B as BackupDestination, g as BackupRunReport } from '../types-BWyv_N18.js';
+export { h as BackupChain, i as BackupChainBase, j as BackupChainChange, k as BackupChainPosition, l as BackupChainRecord, m as BackupCycle, n as BackupCycleError, o as BackupCycleOptions, p as BackupCycleStatus, q as BackupFileReport, r as BackupGroupMembership, s as BackupGroupSource, t as BackupLogPosition, u as BackupNodePreference, v as BackupPiece, w as BackupProgress, x as BackupSkip, y as BackupSkipReason, z as BackupToDestinationOptions, C as BackupVerifyResult, F as DEFAULT_CHAIN_NAME, G as chainLogName, H as readBackupChains, I as verifyBackupRecord } from '../types-BWyv_N18.js';
+export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-BhM8yJ1A.js';
+import { B as BackupRestoreOptions, a as BackupRestoreReport } from '../restore-options-B6HV_5XT.js';
+export { b as BackupRestoreProgress } from '../restore-options-B6HV_5XT.js';
 import '../query-types-5B02ixH0.js';
 
 /** The byte and piece counts for one file that Sirannon assembles from a destination.

package/dist/backup/index.mjs

@@ -1,9 +1,11 @@
-export { assembleFromDestination, restoreBackup } from '../chunk-L6EX6K27.mjs';
-export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YW7IKQ7T.mjs';
+export { assembleFromDestination, restoreBackup } from '../chunk-MO4APBYG.mjs';
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-W74HFQFD.mjs';
+import '../chunk-5DKWHT6K.mjs';
 export { verifyBackupRecord } from '../chunk-DX4WGJL7.mjs';
 import '../chunk-QGVRRKB2.mjs';
 import '../chunk-BUWJH3D3.mjs';
-export { DEFAULT_CHAIN_NAME, chainLogName, readBackupChains } from '../chunk-CZL4D3BM.mjs';
+export { DEFAULT_CHAIN_NAME, chainLogName, readBackupChains } from '../chunk-6CABU54O.mjs';
 import '../chunk-BGJ5JVYL.mjs';
 import '../chunk-HO2XTXVX.mjs';
+import '../chunk-5O4J6LQQ.mjs';
 import '../chunk-KINDFBQP.mjs';

package/dist/backup-scheduler/index.d.ts

@@ -1,5 +1,5 @@
-import { J as SQLiteConnection, K as BackupFileCopy, L as BackupRunRequest, g as BackupRunReport, O as BackupScheduleRequest } from '../types-DTmi7pXp.js';
-export { q as BackupFileReport, P as BackupScheduleOptions, R as RunExclusive } from '../types-DTmi7pXp.js';
+import { L as SQLiteConnection, O as BackupFileCopy, P as BackupRunRequest, g as BackupRunReport, Q as BackupScheduleRequest } from '../types-BWyv_N18.js';
+export { q as BackupFileReport, R as BackupScheduleOptions, U as RunExclusive } from '../types-BWyv_N18.js';
 import '../query-types-5B02ixH0.js';
 
 /** What a runtime supplies so that Sirannon can send a copy to a destination without writing a local file.

package/dist/backup-scheduler/index.mjs

@@ -1,5 +1,5 @@
-export { BackupScheduler } from '../chunk-BTUD6XQO.mjs';
-import '../chunk-W67A4H2E.mjs';
+export { BackupScheduler } from '../chunk-N3MHZV3B.mjs';
+import '../chunk-I4JY5QPA.mjs';
 import '../chunk-AHCMO4YL.mjs';
 import '../chunk-BUWJH3D3.mjs';
 import '../chunk-BGJ5JVYL.mjs';

package/dist/chunk-22TYGH7J.mjs

@@ -0,0 +1,55 @@
+// src/core/driver/statement-text.ts
+var SPACE = 32;
+var TAB = 9;
+var LINE_FEED = 10;
+var VERTICAL_TAB = 11;
+var FORM_FEED = 12;
+var CARRIAGE_RETURN = 13;
+var SEMICOLON = 59;
+var HYPHEN = 45;
+var SLASH = 47;
+var ASTERISK = 42;
+var NO_STATEMENT_MESSAGE = "The supplied SQL string contains no statements";
+function startsSqliteSpace(code) {
+  return code === SPACE || code === TAB || code === LINE_FEED || code === FORM_FEED || code === CARRIAGE_RETURN;
+}
+function continuesSqliteSpace(code) {
+  return startsSqliteSpace(code) || code === VERTICAL_TAB;
+}
+function holdsNoStatement(sql) {
+  const firstNul = sql.indexOf("\0");
+  const text = firstNul === -1 ? sql : sql.slice(0, firstNul);
+  let index = 0;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if (startsSqliteSpace(code)) {
+      index++;
+      while (index < text.length && continuesSqliteSpace(text.charCodeAt(index))) index++;
+      continue;
+    }
+    if (code === SEMICOLON) {
+      index++;
+      continue;
+    }
+    const next = text.charCodeAt(index + 1);
+    if (code === HYPHEN && next === HYPHEN) {
+      const lineEnd = text.indexOf("\n", index + 2);
+      if (lineEnd === -1) return true;
+      index = lineEnd;
+      continue;
+    }
+    if (code === SLASH && next === ASTERISK && index + 2 < text.length) {
+      const commentEnd = text.indexOf("*/", index + 2);
+      if (commentEnd === -1) return true;
+      index = commentEnd + 2;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+function assertHoldsStatement(sql) {
+  if (holdsNoStatement(sql)) throw new RangeError(NO_STATEMENT_MESSAGE);
+}
+
+export { assertHoldsStatement };

package/dist/{chunk-SB3MIFLG.mjs → chunk-2ZQOZFX7.mjs}

@@ -1,9 +1,9 @@
-import { selectOrdinaryTableName, deleteReplacedRowsOfTable, selectMinChangeSeqSql, selectMaxChangeSeq, deleteChangesBeforeUpToSeqSql, deleteAllReplacedRows, selectTableExists, ensureChangesTable, ensureReplacedRowsTable, ensureMetaTable, insertMetaValueIfAbsent, selectMetaValue, selectTriggerSql, selectChangesAfterSeqSql, selectTablesChangesInRangeSql, tableInfoRows, primaryKeyColumns, tableColumnsWithGenerated, tableIndexList, indexColumns, selectTableSql, TABLE_XINFO_HIDDEN, deleteExpiredDeviceCursors, selectMinDeviceCursorBoundary, SEQ_STRING_RE, selectIndexSql } from './chunk-RPWBYASV.mjs';
-import { CDC_TRIGGER_PREFIX, CHANGES_TABLE, isReservedIdentifier, META_TABLE, encodeTaggedValues, REPLACED_ROWS_TABLE, changedAtToEventTimestamp, decodeTaggedValues, DEVICE_CURSORS_TABLE, SAFE_INT_BOUND_TEXT } from './chunk-JFVEGN7J.mjs';
+import { selectOrdinaryTableName, deleteReplacedRowsOfTable, selectMinChangeSeqSql, selectMaxChangeSeq, deleteChangesBeforeUpToSeqSql, deleteAllReplacedRows, selectTableExists, ensureChangesTable, ensureReplacedRowsTable, ensureMetaTable, insertMetaValueIfAbsent, selectMetaValue, selectTriggerSql, selectChangesAfterSeqSql, selectTablesChangesInRangeSql, tableInfoRows, primaryKeyColumns, tableColumnsWithGenerated, tableIndexList, indexColumns, selectTableSql, TABLE_XINFO_HIDDEN, deleteExpiredDeviceCursors, selectMinDeviceCursorBoundary, SEQ_STRING_RE, selectIndexSql } from './chunk-MTOQ6QIS.mjs';
+import { CDC_TRIGGER_PREFIX, CHANGES_TABLE, isReservedIdentifier, META_TABLE, encodeTaggedValues, REPLACED_ROWS_TABLE, changedAtToEventTimestamp, decodeTaggedValues, DEVICE_CURSORS_TABLE, SAFE_INT_BOUND_TEXT } from './chunk-ZAUHAJ4G.mjs';
 import { tokenizeSql, isKeyword } from './chunk-SEL4A4WT.mjs';
-import { synchronousPragmaValue } from './chunk-YCMB6GR4.mjs';
 import { randomHex } from './chunk-BGJ5JVYL.mjs';
 import { invokeCallerCallback, reportCallerFailure, toError } from './chunk-HO2XTXVX.mjs';
+import { synchronousPragmaValue } from './chunk-YCMB6GR4.mjs';
 import { SirannonError, ForbiddenSqlError, CDCError, MigrationError } from './chunk-KINDFBQP.mjs';
 
 // src/core/bulk-load.ts
@@ -666,6 +666,28 @@ function buildJsonObject(columns, ref) {
 function escStr(name) {
   return name.replace(/'/g, "''");
 }
+async function installKeyChangeCaptureTriggers(conn, triggers, table, log, keys) {
+  const logOf = (row) => `INSERT INTO "${escId(log)}" VALUES (${keys.map((key) => `${row}.${key}`).join(", ")});`;
+  const on = `main."${escId(table)}"`;
+  await conn.exec(`CREATE TEMP TRIGGER "${escId(triggers.insert)}" AFTER INSERT ON ${on} BEGIN ${logOf("NEW")} END`);
+  await conn.exec(
+    `CREATE TEMP TRIGGER "${escId(triggers.update)}" AFTER UPDATE ON ${on} BEGIN ${logOf("OLD")} ${logOf("NEW")} END`
+  );
+  await conn.exec(`CREATE TEMP TRIGGER "${escId(triggers.delete)}" AFTER DELETE ON ${on} BEGIN ${logOf("OLD")} END`);
+}
+async function dropKeyChangeCaptureTriggers(conn, triggers) {
+  for (const name of [triggers.insert, triggers.update, triggers.delete]) {
+    await conn.exec(`DROP TRIGGER IF EXISTS temp."${escId(name)}"`);
+  }
+}
+async function dropMainSchemaTriggers(conn) {
+  const triggers = await (await conn.prepare("SELECT name, sql FROM main.sqlite_schema WHERE type = 'trigger' AND sql IS NOT NULL")).all();
+  for (const trigger of triggers) await conn.exec(`DROP TRIGGER main."${escId(trigger.name)}"`);
+  return triggers.map((trigger) => trigger.sql);
+}
+async function createMainSchemaTriggers(conn, statements) {
+  for (const statement of statements) await conn.exec(statement);
+}
 
 // src/core/cdc/change-tracker.ts
 var DEFAULT_RETENTION_MS = 36e5;
@@ -1155,7 +1177,7 @@ var SubscriptionBuilderImpl = class {
     return this.manager.subscribe(this.table, this.conditions, callback, options);
   }
 };
-function startPolling(conn, tracker, manager, intervalMs, onError, runExclusive, deviceRetention = {
+function startPolling(connection, tracker, manager, intervalMs, onError, runExclusive, deviceRetention = {
   cursorRetentionMs: DEFAULT_DEVICE_CURSOR_RETENTION_MS,
   maxChangesHeldForDevice: 0
 }) {
@@ -1170,7 +1192,7 @@ function startPolling(conn, tracker, manager, intervalMs, onError, runExclusive,
     if (polling) return;
     polling = true;
     try {
-      const events = await exclusive(() => tracker.poll(conn));
+      const events = await exclusive(() => tracker.poll(connection()));
       if (events.length > 0) {
         manager.dispatch(events);
       }
@@ -1180,6 +1202,7 @@ function startPolling(conn, tracker, manager, intervalMs, onError, runExclusive,
       if (tickCount >= CLEANUP_INTERVAL_TICKS) {
         tickCount = 0;
         await exclusive(async () => {
+          const conn = connection();
           await applyDeviceCursorBoundary(conn, tracker, deviceRetention);
           await tracker.cleanup(conn);
         });
@@ -1371,4 +1394,4 @@ var TransactionGrouper = class {
   }
 };
 
-export { ChangeTracker, DEVICE_SYNC_PUSHED_SEQ_META_KEY, PrimedSubscription, ROWID_ALIASES, SubscriptionBuilderImpl, SubscriptionManager, TransactionGrouper, applyDeviceCursorBoundary, dropCdcTriggers, ensureCdcEpoch, filteredChange, isBulkLoadDurability, migrationChecksum, migrationContentChecksum, needsResync, parseColumnDefinitions, reconcileMigrationChecksums, resolveDeviceRetentionPolicy, runBulkLoad, startPolling };
+export { ChangeTracker, DEVICE_SYNC_PUSHED_SEQ_META_KEY, PrimedSubscription, ROWID_ALIASES, SubscriptionBuilderImpl, SubscriptionManager, TransactionGrouper, applyDeviceCursorBoundary, createMainSchemaTriggers, dropCdcTriggers, dropKeyChangeCaptureTriggers, dropMainSchemaTriggers, ensureCdcEpoch, escId, filteredChange, installKeyChangeCaptureTriggers, isBulkLoadDurability, migrationChecksum, migrationContentChecksum, needsResync, parseColumnDefinitions, reconcileMigrationChecksums, resolveDeviceRetentionPolicy, runBulkLoad, startPolling };

package/dist/{chunk-UIDQGPJY.mjs → chunk-4O7WYZHN.mjs}

@@ -883,7 +883,7 @@ var AckPayload = {
   }
 };
 function createBaseHello() {
-  return { nodeId: "", role: "", groupId: "", primaryTerm: 0n, protocolVersion: "" };
+  return { nodeId: "", role: "", groupId: "", primaryTerm: 0n, protocolVersion: "", encrypted: false };
 }
 var Hello = {
   encode(message, writer = new BinaryWriter()) {
@@ -905,6 +905,9 @@ var Hello = {
     if (message.protocolVersion !== "") {
       writer.uint32(42).string(message.protocolVersion);
     }
+    if (message.encrypted !== false) {
+      writer.uint32(48).bool(message.encrypted);
+    }
     return writer;
   },
   decode(input, length) {
@@ -949,6 +952,13 @@ var Hello = {
           message.protocolVersion = reader.string();
           continue;
         }
+        case 6: {
+          if (tag !== 48) {
+            break;
+          }
+          message.encrypted = reader.bool();
+          continue;
+        }
       }
       if ((tag & 7) === 4 || tag === 0) {
         break;
@@ -963,7 +973,8 @@ var Hello = {
       role: isSet(object.role) ? globalThis.String(object.role) : "",
       groupId: isSet(object.groupId) ? globalThis.String(object.groupId) : isSet(object.group_id) ? globalThis.String(object.group_id) : "",
       primaryTerm: isSet(object.primaryTerm) ? BigInt(object.primaryTerm) : isSet(object.primary_term) ? BigInt(object.primary_term) : 0n,
-      protocolVersion: isSet(object.protocolVersion) ? globalThis.String(object.protocolVersion) : isSet(object.protocol_version) ? globalThis.String(object.protocol_version) : ""
+      protocolVersion: isSet(object.protocolVersion) ? globalThis.String(object.protocolVersion) : isSet(object.protocol_version) ? globalThis.String(object.protocol_version) : "",
+      encrypted: isSet(object.encrypted) ? globalThis.Boolean(object.encrypted) : false
     };
   },
   toJSON(message) {
@@ -983,6 +994,9 @@ var Hello = {
     if (message.protocolVersion !== "") {
       obj.protocolVersion = message.protocolVersion;
     }
+    if (message.encrypted !== false) {
+      obj.encrypted = message.encrypted;
+    }
     return obj;
   },
   create(base) {
@@ -995,6 +1009,7 @@ var Hello = {
     message.groupId = object.groupId ?? "";
     message.primaryTerm = object.primaryTerm ?? 0n;
     message.protocolVersion = object.protocolVersion ?? "";
+    message.encrypted = object.encrypted ?? false;
     return message;
   }
 };
@@ -2639,4 +2654,24 @@ function buildChannelCreds(options) {
   return credentials.createSsl(ca, key, cert);
 }
 
-export { ReplicationClient, ReplicationService, buildChannelCreds, buildServerCreds };
+// src/transport/grpc/hello.ts
+function localHello(t) {
+  return {
+    nodeId: t.localNodeId,
+    role: t.localRole,
+    groupId: t.localGroupId ?? "",
+    primaryTerm: t.localPrimaryTerm ?? 0n,
+    protocolVersion: t.localProtocolVersion ?? "",
+    encrypted: t.localEncrypted
+  };
+}
+function peerHelloFields(hello) {
+  return {
+    groupId: hello.groupId || void 0,
+    primaryTerm: hello.primaryTerm === 0n ? void 0 : hello.primaryTerm,
+    protocolVersion: hello.protocolVersion || void 0,
+    encrypted: hello.encrypted === true
+  };
+}
+
+export { ReplicationClient, ReplicationService, buildChannelCreds, buildServerCreds, localHello, peerHelloFields };

package/dist/{chunk-ZFFUVYYE.mjs → chunk-5DKWHT6K.mjs}

@@ -94,6 +94,54 @@ function getDotPath(issue) {
   return null;
 }
 // @__NO_SIDE_EFFECTS__
+function check(requirement, message$1) {
+  return {
+    kind: "validation",
+    type: "check",
+    reference: check,
+    async: false,
+    expects: null,
+    requirement,
+    message: message$1,
+    "~run"(dataset, config$1) {
+      if (dataset.typed && !this.requirement(dataset.value)) _addIssue(this, "input", dataset, config$1);
+      return dataset;
+    }
+  };
+}
+// @__NO_SIDE_EFFECTS__
+function maxLength(requirement, message$1) {
+  return {
+    kind: "validation",
+    type: "max_length",
+    reference: maxLength,
+    async: false,
+    expects: `<=${requirement}`,
+    requirement,
+    message: message$1,
+    "~run"(dataset, config$1) {
+      if (dataset.typed && dataset.value.length > this.requirement) _addIssue(this, "length", dataset, config$1, { received: `${dataset.value.length}` });
+      return dataset;
+    }
+  };
+}
+// @__NO_SIDE_EFFECTS__
+function minLength(requirement, message$1) {
+  return {
+    kind: "validation",
+    type: "min_length",
+    reference: minLength,
+    async: false,
+    expects: `>=${requirement}`,
+    requirement,
+    message: message$1,
+    "~run"(dataset, config$1) {
+      if (dataset.typed && dataset.value.length < this.requirement) _addIssue(this, "length", dataset, config$1, { received: `${dataset.value.length}` });
+      return dataset;
+    }
+  };
+}
+// @__NO_SIDE_EFFECTS__
 function regex(requirement, message$1) {
   return {
     kind: "validation",
@@ -163,6 +211,23 @@ function array(item, message$1) {
   });
 }
 // @__NO_SIDE_EFFECTS__
+function instance(class_, message$1) {
+  return _standardSchema({
+    kind: "schema",
+    type: "instance",
+    reference: instance,
+    expects: class_.name,
+    async: false,
+    class: class_,
+    message: message$1,
+    "~run"(dataset, config$1) {
+      if (dataset.value instanceof this.class) dataset.typed = true;
+      else _addIssue(this, "type", dataset, config$1);
+      return dataset;
+    }
+  });
+}
+// @__NO_SIDE_EFFECTS__
 function nullable(wrapped, default_) {
   return _standardSchema({
     kind: "schema",
@@ -383,6 +448,49 @@ function string(message$1) {
   });
 }
 // @__NO_SIDE_EFFECTS__
+function _subIssues(datasets) {
+  let issues;
+  if (datasets) for (const dataset of datasets) if (issues) for (const issue of dataset.issues) issues.push(issue);
+  else issues = dataset.issues;
+  return issues;
+}
+// @__NO_SIDE_EFFECTS__
+function union(options, message$1) {
+  return _standardSchema({
+    kind: "schema",
+    type: "union",
+    reference: union,
+    expects: /* @__PURE__ */ _joinExpects(options.map((option) => option.expects), "|"),
+    async: false,
+    options,
+    message: message$1,
+    "~run"(dataset, config$1) {
+      let validDataset;
+      let typedDatasets;
+      let untypedDatasets;
+      for (const schema of this.options) {
+        const optionDataset = schema["~run"]({ value: dataset.value }, config$1);
+        if (optionDataset.typed) if (optionDataset.issues) if (typedDatasets) typedDatasets.push(optionDataset);
+        else typedDatasets = [optionDataset];
+        else {
+          validDataset = optionDataset;
+          break;
+        }
+        else if (untypedDatasets) untypedDatasets.push(optionDataset);
+        else untypedDatasets = [optionDataset];
+      }
+      if (validDataset) return validDataset;
+      if (typedDatasets) {
+        if (typedDatasets.length === 1) return typedDatasets[0];
+        _addIssue(this, "type", dataset, config$1, { issues: /* @__PURE__ */ _subIssues(typedDatasets) });
+        dataset.typed = true;
+      } else if (untypedDatasets?.length === 1) return untypedDatasets[0];
+      else _addIssue(this, "type", dataset, config$1, { issues: /* @__PURE__ */ _subIssues(untypedDatasets) });
+      return dataset;
+    }
+  });
+}
+// @__NO_SIDE_EFFECTS__
 function unknown() {
   return _standardSchema({
     kind: "schema",
@@ -436,4 +544,4 @@ function summarize(issues) {
   return summary;
 }
 
-export { array, getDotPath, nullable, number, object, optional, picklist, pipe, record, regex, safeParse, string, summarize, unknown };
+export { array, check, getDotPath, instance, maxLength, minLength, nullable, number, object, optional, picklist, pipe, record, regex, safeParse, string, summarize, union, unknown };

package/dist/chunk-5O4J6LQQ.mjs

@@ -0,0 +1,35 @@
+import { SirannonError } from './chunk-KINDFBQP.mjs';
+
+// src/core/encryption/errors.ts
+var EncryptionError = class extends SirannonError {
+  /**
+   * Returns an error with an encryption code, and the failure that caused it when there is one.
+   *
+   * @param message - What failed, written without the key.
+   * @param code - The machine-readable code.
+   * @param cause - The failure that caused this error, such as the error that a key function threw.
+   */
+  constructor(message, code, cause) {
+    super(message, code);
+    this.name = "EncryptionError";
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: cause, enumerable: false, writable: true, configurable: true });
+    }
+  }
+};
+function keyRejected(path, cause) {
+  return new EncryptionError(
+    `The key failed the authentication check of the first page of the database ${path}. Either the key is wrong, or the file comes from another encryption scheme: the better-sqlite3 driver encrypts with AEGIS-256 and the Expo driver encrypts with SQLCipher 4, and neither opens the other's files`,
+    "ENCRYPTION_KEY_REJECTED",
+    cause
+  );
+}
+function refuseEncryptedOpen(driverName, options) {
+  if (options?.encryption === void 0) return;
+  throw new EncryptionError(
+    `The ${driverName} driver opens SQLite through a library that Sirannon cannot replace with an encrypting build, so it cannot open an encrypted database`,
+    "ENCRYPTION_UNSUPPORTED"
+  );
+}
+
+export { EncryptionError, keyRejected, refuseEncryptedOpen };

package/dist/{chunk-CZL4D3BM.mjs → chunk-6CABU54O.mjs}

@@ -20,11 +20,11 @@ function isBackupChainHead(value) {
 }
 function isBackupChainBase(value) {
   const base = value;
-  return base?.kind === "full" && typeof base.chainId === "string" && typeof base.name === "string" && typeof base.runId === "string" && isWholeNumber(base.finishedAt) && isWholeNumber(base.pieceCount) && isAtLeastOne(base.pieceBytes) && isWholeNumber(base.bytesWritten) && isTextOrAbsent(base.fingerprint);
+  return base?.kind === "full" && typeof base.chainId === "string" && typeof base.name === "string" && typeof base.runId === "string" && isWholeNumber(base.finishedAt) && isWholeNumber(base.pieceCount) && isAtLeastOne(base.pieceBytes) && isWholeNumber(base.bytesWritten) && isTextOrAbsent(base.fingerprint) && isTextOrAbsent(base.keyId);
 }
 function isBackupChainChange(value) {
   const change = value;
-  return change?.kind === "change" && typeof change.chainId === "string" && typeof change.name === "string" && typeof change.runId === "string" && isAtLeastOne(change.sequence) && isBackupChainPosition(change.position) && isWholeNumber(change.capturedAt) && isAtLeastOne(change.frameCount) && isWholeNumber(change.pieceCount) && isAtLeastOne(change.pieceBytes) && isWholeNumber(change.bytesWritten) && typeof change.checkpointed === "boolean" && isTextOrAbsent(change.fingerprint);
+  return change?.kind === "change" && typeof change.chainId === "string" && typeof change.name === "string" && typeof change.runId === "string" && isAtLeastOne(change.sequence) && isBackupChainPosition(change.position) && isWholeNumber(change.capturedAt) && isAtLeastOne(change.frameCount) && isWholeNumber(change.pieceCount) && isAtLeastOne(change.pieceBytes) && isWholeNumber(change.bytesWritten) && typeof change.checkpointed === "boolean" && isTextOrAbsent(change.fingerprint) && isTextOrAbsent(change.keyId);
 }
 
 // src/core/backup/chain.ts

package/dist/{chunk-JAQ2I4OT.mjs → chunk-A5ULJVK7.mjs}

@@ -1,6 +1,13 @@
 import { SirannonError } from './chunk-KINDFBQP.mjs';
 
 // src/core/driver/define.ts
+function boundFileSystem(files) {
+  return Object.freeze({
+    readStart: files.readStart.bind(files),
+    remove: files.remove.bind(files),
+    rename: files.rename.bind(files)
+  });
+}
 function defineDriver(config) {
   if (!config.capabilities || typeof config.open !== "function") {
     throw new SirannonError("Driver must define capabilities and open()", "INVALID_DRIVER");
@@ -9,22 +16,15 @@ function defineDriver(config) {
     throw new SirannonError("Driver worker entry must define a string specifier", "INVALID_DRIVER");
   }
   return Object.freeze({
-    capabilities: Object.freeze({ ...config.capabilities }),
+    capabilities: Object.freeze({ ...config.capabilities, encryption: config.capabilities.encryption === true }),
     open: config.open.bind(config),
     ...config.worker ? { worker: Object.freeze({ ...config.worker }) } : {},
     ...config.startWriterHost ? { startWriterHost: config.startWriterHost.bind(config) } : {},
     ...config.createWriterContext ? { createWriterContext: config.createWriterContext.bind(config) } : {},
     ...config.createBackupEngine ? { createBackupEngine: config.createBackupEngine.bind(config) } : {},
-    ...config.resolveExtensionPath ? { resolveExtensionPath: config.resolveExtensionPath.bind(config) } : {}
+    ...config.resolveExtensionPath ? { resolveExtensionPath: config.resolveExtensionPath.bind(config) } : {},
+    ...config.files ? { files: boundFileSystem(config.files) } : {}
   });
 }
 
-// src/core/backup/cycle-options.ts
-var DEFAULT_CAPTURE_INTERVAL_MS = 6e4;
-var DEFAULT_FULL_COPY_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-var DEFAULT_BACKUP_NAME_PREFIX = "sirannon-backup";
-function defaultStagingDir(sourcePath) {
-  return `${sourcePath}-backup`;
-}
-
-export { DEFAULT_BACKUP_NAME_PREFIX, DEFAULT_CAPTURE_INTERVAL_MS, DEFAULT_FULL_COPY_INTERVAL_MS, defaultStagingDir, defineDriver };
+export { defineDriver };

package/dist/{chunk-RLBKZZ24.mjs → chunk-AC7TKWNH.mjs}

@@ -19,6 +19,7 @@ function registerPeer(connectedPeers, peerConnectedHandler, nodeId, role, metada
     role,
     primaryTerm: metadata.primaryTerm,
     protocolVersion: metadata.protocolVersion,
+    encrypted: metadata.encrypted === true,
     joinedAt: Date.now(),
     lastSeenAt: Date.now(),
     lastAckedSeq: 0n