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

package/dist/{server-options-B9CsAZp5.d.ts → server-options-Bhdlvehe.d.ts}

@@ -1,6 +1,6 @@
+import { N as NodeHealth, T as Transaction, J as EncryptionKey, K as ClusterStatusInfo } from './types-BWyv_N18.js';
 import { a as OperationRegistry, D as DatabaseOperations } from './operation-registry-CGhNT-Sn.js';
 import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult } from './types-BG31TtrQ.js';
-import { N as NodeHealth, T as Transaction, I as ClusterStatusInfo } from './types-DTmi7pXp.js';
 import { P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-5B02ixH0.js';
 
 /**
@@ -202,6 +202,19 @@ interface ServerOptions<Identity = unknown> {
      * hook.
      */
     acceptBackupRestore?: boolean;
+    /**
+     * Enables `POST /db/{id}/encryption`, which encrypts a database, changes its key, or removes encryption while the
+     * server serves it; the default is false. The server constructor throws `INVALID_ENCRYPTION_CHANGE` when you enable
+     * it without an `authenticate` hook or without {@link ServerOptions.encryptionKeys}.
+     */
+    acceptEncryptionChange?: boolean;
+    /**
+     * Returns the key that a `keyRef` in an encryption request refers to, so that the caller sends the server a name and
+     * the key stays on the server. Return 32 random bytes, or `{ key, id }` to store an identifier with the key. The
+     * server calls it once to check the key before it answers, and again each time the database opens its connections
+     * under that key.
+     */
+    encryptionKeys?: (databaseId: string, keyRef: string) => EncryptionKey | Promise<EncryptionKey>;
     /** Enables device sync, which covers the push, snapshot, and migration-list routes, device subscriptions, and acknowledgements; the default is false. The server constructor throws `INVALID_DEVICE_SYNC` when you enable it without an `authenticate` hook. */
     acceptDeviceSync?: boolean;
     /** Returns the target that the server executes a database's statements against; without it, the server uses the databases in its own registry. */

package/dist/{server-streams-SBYCHWWM.mjs → server-streams-Q2AZAW3N.mjs}

@@ -1,6 +1,6 @@
+import { ReplicationService, buildServerCreds, localHello, peerHelloFields } from './chunk-4O7WYZHN.mjs';
 import { SERVICE_NAME } from './chunk-BVMZJOVM.mjs';
-import { ReplicationService, buildServerCreds } from './chunk-UIDQGPJY.mjs';
-import { restartPeerConnection, registerPeer, removePeer } from './chunk-RLBKZZ24.mjs';
+import { restartPeerConnection, registerPeer, removePeer } from './chunk-AC7TKWNH.mjs';
 import { fromForwardRequest, fromBatchPayload, fromAckPayload, fromSyncRequestPayload, fromSyncBatchPayload, fromSyncCompletePayload, fromSyncAckPayload } from './chunk-3VTT3VU6.mjs';
 import { TransportError } from './chunk-KU32OT4H.mjs';
 import './chunk-BLMRNSUG.mjs';
@@ -77,22 +77,10 @@ function handleServerReplicateStream(t, call) {
       t.serverPeerStreams.set(peerId, ps);
       if (replaced) restartPeerConnection(t.connectedPeers, t.peerDisconnectedHandler, peerId);
       if (!helloSent) {
-        call.write({
-          hello: {
-            nodeId: t.localNodeId,
-            role: t.localRole,
-            groupId: t.localGroupId ?? "",
-            primaryTerm: t.localPrimaryTerm ?? 0n,
-            protocolVersion: t.localProtocolVersion ?? ""
-          }
-        });
+        call.write({ hello: localHello(t) });
         helloSent = true;
       }
-      registerPeer(t.connectedPeers, t.peerConnectedHandler, peerId, peerRole, {
-        groupId: msg.hello.groupId || void 0,
-        primaryTerm: msg.hello.primaryTerm === 0n ? void 0 : msg.hello.primaryTerm,
-        protocolVersion: msg.hello.protocolVersion || void 0
-      });
+      registerPeer(t.connectedPeers, t.peerConnectedHandler, peerId, peerRole, peerHelloFields(msg.hello));
       return;
     }
     if (msg.batch) {
@@ -139,22 +127,10 @@ function handleServerSyncStream(t, call) {
       ps.syncStream = call;
       t.serverPeerStreams.set(peerId, ps);
       if (!helloSent) {
-        call.write({
-          hello: {
-            nodeId: t.localNodeId,
-            role: t.localRole,
-            groupId: t.localGroupId ?? "",
-            primaryTerm: t.localPrimaryTerm ?? 0n,
-            protocolVersion: t.localProtocolVersion ?? ""
-          }
-        });
+        call.write({ hello: localHello(t) });
         helloSent = true;
       }
-      registerPeer(t.connectedPeers, t.peerConnectedHandler, peerId, peerRole, {
-        groupId: msg.hello.groupId || void 0,
-        primaryTerm: msg.hello.primaryTerm === 0n ? void 0 : msg.hello.primaryTerm,
-        protocolVersion: msg.hello.protocolVersion || void 0
-      });
+      registerPeer(t.connectedPeers, t.peerConnectedHandler, peerId, peerRole, peerHelloFields(msg.hello));
       return;
     }
     if (msg.syncRequest) {

package/dist/{sirannon-D0CjDULa.d.ts → sirannon-Ba1o2HUQ.d.ts}

@@ -1,5 +1,5 @@
-import { H as HookRegistry, D as Database, a as HookDispose } from './database-fz-8CJBP.js';
-import { a as SirannonOptions, S as SQLiteDriver, b as MetricsCollector, D as DatabaseOptions, M as Migration, c as BeforeQueryHook, A as AfterQueryHook, d as BeforeConnectHook, e as DatabaseOpenHook, f as DatabaseCloseHook } from './types-DTmi7pXp.js';
+import { H as HookRegistry, D as Database, a as HookDispose } from './database-BZ96ZzAx.js';
+import { a as SirannonOptions, S as SQLiteDriver, b as MetricsCollector, D as DatabaseOptions, E as EncryptionOptions, M as Migration, c as BeforeQueryHook, A as AfterQueryHook, d as BeforeConnectHook, e as DatabaseOpenHook, f as DatabaseCloseHook } from './types-BWyv_N18.js';
 
 /** The outcome of taking one database offline.
  * @internal
@@ -80,13 +80,13 @@ declare class Sirannon {
      * Sirannon reopens the database even after a failed action.
      *
      * @param id - The identifier of the database to take offline.
-     * @param action - The function that Sirannon calls with the database file path once the database is closed.
+     * @param action - The function that Sirannon calls with the database file path and its key once the database is closed.
      * @returns Whether the action returned, the value that it returned or the error that it threw, and any error that the reopen threw.
-     * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, or the close error when the close fails.
+     * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, a `ReplicationError` with `REPLICATION_ACTIVE` while a replication engine writes to the database, or the close error when the close fails.
      *
      * @internal
      */
-    withDatabaseOffline<T>(id: string, action: (path: string) => Promise<T>): Promise<OfflineOutcome<T>>;
+    withDatabaseOffline<T>(id: string, action: (path: string, encryption?: EncryptionOptions) => Promise<T>): Promise<OfflineOutcome<T>>;
     /**
      * Returns an already-open database.
      *

package/dist/transport/grpc.d.ts

@@ -1,10 +1,10 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Client, ClientDuplexStream, CallOptions, Metadata, ServiceError, ClientUnaryCall, ChannelCredentials, ClientOptions, ServerDuplexStream, Server } from '@grpc/grpc-js';
 import { HealthImplementation } from 'grpc-health-check';
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-BlZ9GG1a.js';
+import { S as SirannonError } from '../errors-DLMAGQFb.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-CDnlkVRK.js';
 import { R as ReplicationBatch } from '../types-BG31TtrQ.js';
-import '../change-tracker-Dpo99EI-.js';
-import '../types-DTmi7pXp.js';
+import '../types-BWyv_N18.js';
 import '../query-types-5B02ixH0.js';
 import '../types-MczwKtul.js';
 
@@ -68,6 +68,7 @@ interface Hello {
     groupId: string;
     primaryTerm: bigint;
     protocolVersion: string;
+    encrypted: boolean;
 }
 declare const Hello: MessageFns<Hello>;
 interface ReplicationMessage {
@@ -324,6 +325,8 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     /** @internal */
     localProtocolVersion: string | undefined;
     /** @internal */
+    localEncrypted: boolean;
+    /** @internal */
     connected: boolean;
     /** @internal */
     server: Server | null;
@@ -398,6 +401,14 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     sendSyncComplete(peerId: string, complete: SyncComplete): Promise<void>;
     /** Tells the source whether this joining node stored one first-sync page. */
     sendSyncAck(peerId: string, ack: SyncAck): Promise<void>;
+    /**
+     * Ends every stream with one peer, and carries the error's code to the peer in the `sirannon-error-code` trailer of
+     * each stream that the peer opened.
+     *
+     * @param peerId - The peer to refuse.
+     * @param error - The error whose code the streams carry, such as `ENCRYPTION_REQUIRED`.
+     */
+    refusePeer(peerId: string, error: SirannonError): Promise<void>;
     /** Registers the handler that applies incoming change batches. */
     onBatchReceived(handler: BatchHandler): void;
     /** Registers the handler that records incoming acknowledgements. */
@@ -429,7 +440,7 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     }): string | null;
     private ensureConnected;
     private getReplicateWriteStream;
-    private getSyncWriteStream;
+    private writeSync;
 }
 
 export { type GrpcReplicationOptions, GrpcReplicationTransport, fromColumnValue, toColumnValue };

package/dist/transport/grpc.mjs

@@ -1,6 +1,6 @@
 import { SERVICE_NAME, DEFAULT_FORWARD_DEADLINE_MS } from '../chunk-BVMZJOVM.mjs';
-import { replaceWantedEndpoints, stopEndpointDialling } from '../chunk-KOTBP4AW.mjs';
-import { peerIdForServerStream, replicateWriteStream, syncWriteStream } from '../chunk-RLBKZZ24.mjs';
+import { replaceWantedEndpoints, stopEndpointDialling } from '../chunk-C7E4H6UN.mjs';
+import { peerIdForServerStream, replicateWriteStream, syncWriteStream } from '../chunk-AC7TKWNH.mjs';
 import { toBatchPayload, toAckPayload, toSyncRequestPayload, toSyncBatchPayload, toSyncCompletePayload, toSyncAckPayload } from '../chunk-3VTT3VU6.mjs';
 export { fromColumnValue, toColumnValue } from '../chunk-3VTT3VU6.mjs';
 import { TransportError } from '../chunk-KU32OT4H.mjs';
@@ -29,15 +29,17 @@ async function loadGrpcRuntime() {
   await requirePackage("@grpc/grpc-js", () => import('@grpc/grpc-js'));
   await requirePackage("@bufbuild/protobuf", () => import('@bufbuild/protobuf/wire'));
   await requirePackage("grpc-health-check", () => import('grpc-health-check'));
-  const [serverStreams, clientStreams, forwardRpc] = await Promise.all([
-    import('../server-streams-SBYCHWWM.mjs'),
-    import('../client-streams-MKPE4MXW.mjs'),
-    import('../forward-rpc-S7NMLBX7.mjs')
+  const [serverStreams, clientStreams, forwardRpc, peerRefusal] = await Promise.all([
+    import('../server-streams-Q2AZAW3N.mjs'),
+    import('../client-streams-F7IG3PTU.mjs'),
+    import('../forward-rpc-S7NMLBX7.mjs'),
+    import('../peer-refusal-RR37UOLV.mjs')
   ]);
   return {
     startServer: serverStreams.startServer,
     connectToEndpoint: clientStreams.connectToEndpoint,
-    forwardOverRpc: forwardRpc.forwardOverRpc
+    forwardOverRpc: forwardRpc.forwardOverRpc,
+    refusePeerStreams: peerRefusal.refusePeerStreams
   };
 }
 
@@ -116,6 +118,8 @@ var GrpcReplicationTransport = class {
   /** @internal */
   localProtocolVersion;
   /** @internal */
+  localEncrypted = false;
+  /** @internal */
   connected = false;
   /** @internal */
   server = null;
@@ -181,6 +185,7 @@ var GrpcReplicationTransport = class {
     this.localGroupId = config.groupId;
     this.localPrimaryTerm = config.primaryTerm;
     this.localProtocolVersion = config.protocolVersion;
+    this.localEncrypted = config.encrypted === true;
     this.connected = true;
     if (this.localRole === "primary" || config.groupId) {
       await runtime.startServer(this);
@@ -285,43 +290,30 @@ var GrpcReplicationTransport = class {
   }
   /** Asks a peer to stream a full copy of the database. */
   async requestSync(peerId, request) {
-    this.ensureConnected();
-    const stream = this.getSyncWriteStream(peerId);
-    if (!stream) {
-      throw new TransportError(`Peer '${peerId}' is not connected`);
-    }
-    const msg = { syncRequest: toSyncRequestPayload(request) };
-    await writeWithBackpressure(stream, msg);
+    await this.writeSync(peerId, () => ({ syncRequest: toSyncRequestPayload(request) }));
   }
   /** Sends one page of first-sync table data. */
   async sendSyncBatch(peerId, batch) {
-    this.ensureConnected();
-    const stream = this.getSyncWriteStream(peerId);
-    if (!stream) {
-      throw new TransportError(`Peer '${peerId}' is not connected`);
-    }
-    const msg = { syncBatch: toSyncBatchPayload(batch) };
-    await writeWithBackpressure(stream, msg);
+    await this.writeSync(peerId, () => ({ syncBatch: toSyncBatchPayload(batch) }));
   }
   /** Tells a joining node that first sync is complete, and sends the manifests that the node checks its copy against. */
   async sendSyncComplete(peerId, complete) {
-    this.ensureConnected();
-    const stream = this.getSyncWriteStream(peerId);
-    if (!stream) {
-      throw new TransportError(`Peer '${peerId}' is not connected`);
-    }
-    const msg = { syncComplete: toSyncCompletePayload(complete) };
-    await writeWithBackpressure(stream, msg);
+    await this.writeSync(peerId, () => ({ syncComplete: toSyncCompletePayload(complete) }));
   }
   /** Tells the source whether this joining node stored one first-sync page. */
   async sendSyncAck(peerId, ack) {
-    this.ensureConnected();
-    const stream = this.getSyncWriteStream(peerId);
-    if (!stream) {
-      throw new TransportError(`Peer '${peerId}' is not connected`);
-    }
-    const msg = { syncAck: toSyncAckPayload(ack) };
-    await writeWithBackpressure(stream, msg);
+    await this.writeSync(peerId, () => ({ syncAck: toSyncAckPayload(ack) }));
+  }
+  /**
+   * Ends every stream with one peer, and carries the error's code to the peer in the `sirannon-error-code` trailer of
+   * each stream that the peer opened.
+   *
+   * @param peerId - The peer to refuse.
+   * @param error - The error whose code the streams carry, such as `ENCRYPTION_REQUIRED`.
+   */
+  async refusePeer(peerId, error) {
+    if (!this.connected || !this.runtime) return;
+    this.runtime.refusePeerStreams(this, peerId, error);
   }
   /** Registers the handler that applies incoming change batches. */
   onBatchReceived(handler) {
@@ -394,8 +386,13 @@ var GrpcReplicationTransport = class {
   getReplicateWriteStream(peerId) {
     return replicateWriteStream(this.serverPeerStreams, this.clientPeerStreams, peerId);
   }
-  getSyncWriteStream(peerId) {
-    return syncWriteStream(this.serverPeerStreams, this.clientPeerStreams, peerId);
+  async writeSync(peerId, message) {
+    this.ensureConnected();
+    const stream = syncWriteStream(this.serverPeerStreams, this.clientPeerStreams, peerId);
+    if (!stream) {
+      throw new TransportError(`Peer '${peerId}' is not connected`);
+    }
+    await writeWithBackpressure(stream, message());
   }
 };
 

package/dist/transport/memory.d.ts

@@ -1,7 +1,7 @@
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-BlZ9GG1a.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-CDnlkVRK.js';
 import { R as ReplicationBatch } from '../types-BG31TtrQ.js';
-import '../change-tracker-Dpo99EI-.js';
-import '../types-DTmi7pXp.js';
+import '../errors-DLMAGQFb.js';
+import '../types-BWyv_N18.js';
 import '../query-types-5B02ixH0.js';
 import '../types-MczwKtul.js';
 
@@ -34,6 +34,7 @@ declare class InMemoryTransport implements ReplicationTransport {
     private localGroupId;
     private localPrimaryTerm;
     private localProtocolVersion;
+    private localEncrypted;
     private connected;
     private readonly bus;
     private readonly connectedPeers;

package/dist/transport/memory.mjs

@@ -1,3 +1,7 @@
+import { TransportError } from '../chunk-KU32OT4H.mjs';
+import '../chunk-BLMRNSUG.mjs';
+import '../chunk-KINDFBQP.mjs';
+
 // src/transport/memory/bus.ts
 var MemoryBus = class {
   transports = /* @__PURE__ */ new Map();
@@ -23,32 +27,6 @@ var MemoryBus = class {
   }
 };
 
-// src/core/errors.ts
-var SirannonError = class extends Error {
-  constructor(message, code) {
-    super(message);
-    this.code = code;
-    this.name = "SirannonError";
-  }
-};
-
-// src/core/sync/errors.ts
-var ReplicationError = class extends SirannonError {
-  constructor(message, code = "REPLICATION_ERROR", details) {
-    super(message, code);
-    this.details = details;
-    this.name = "ReplicationError";
-  }
-};
-
-// src/replication/errors.ts
-var TransportError = class extends ReplicationError {
-  constructor(message) {
-    super(message, "TRANSPORT_ERROR");
-    this.name = "TransportError";
-  }
-};
-
 // src/transport/validators.ts
 function isValidBatch(batch) {
   if (typeof batch !== "object" || batch === null) return false;
@@ -117,6 +95,7 @@ var InMemoryTransport = class {
   localGroupId;
   localPrimaryTerm;
   localProtocolVersion;
+  localEncrypted = false;
   connected = false;
   bus;
   connectedPeers = /* @__PURE__ */ new Map();
@@ -145,6 +124,7 @@ var InMemoryTransport = class {
     this.localGroupId = config.groupId;
     this.localPrimaryTerm = config.primaryTerm;
     this.localProtocolVersion = config.protocolVersion;
+    this.localEncrypted = config.encrypted === true;
     this.connected = true;
     this.bus.join(localNodeId, this);
     for (const peerId of this.bus.peerIds()) {
@@ -157,6 +137,7 @@ var InMemoryTransport = class {
         role: peerTransport.role,
         primaryTerm: peerTransport.localPrimaryTerm,
         protocolVersion: peerTransport.localProtocolVersion,
+        encrypted: peerTransport.localEncrypted,
         joinedAt: Date.now(),
         lastSeenAt: Date.now(),
         lastAckedSeq: 0n
@@ -168,6 +149,7 @@ var InMemoryTransport = class {
         role: this.localRole,
         primaryTerm: this.localPrimaryTerm,
         protocolVersion: this.localProtocolVersion,
+        encrypted: this.localEncrypted,
         joinedAt: Date.now(),
         lastSeenAt: Date.now(),
         lastAckedSeq: 0n

package/dist/{types-DTmi7pXp.d.ts → types-BWyv_N18.d.ts}

@@ -88,6 +88,8 @@ interface BackupChainBase {
     bytesWritten: number;
     /** The SHA-256 of the copy, present while fingerprinting is on. */
     fingerprint?: string;
+    /** The identifier that came with the key that this copy holds ciphertext under, where the key came with one. */
+    keyId?: string;
 }
 /**
  * One change piece, which holds the log frames that a database writes between
@@ -122,6 +124,8 @@ interface BackupChainChange {
     checkpointed: boolean;
     /** The SHA-256 of the frames, present while fingerprinting is on. */
     fingerprint?: string;
+    /** The identifier that came with the key that these frames hold ciphertext under, where the key came with one. */
+    keyId?: string;
 }
 /** Either the full copy at the head of a chain or one change piece along it.
  * @public
@@ -557,6 +561,8 @@ interface BackupCycleRequest extends BackupCycleOptions {
     acquireWriter: () => SQLiteConnection;
     /** Copies the whole database to the destination as the full copy that starts each chain. */
     fullCopy: (options: BackupToDestinationOptions) => Promise<BackupRunReport>;
+    /** Returns the identifier that came with the database's current key, which each chain record stores. */
+    keyId?: () => string | undefined;
 }
 
 /** A failure of one turn of the cycle.
@@ -753,6 +759,8 @@ declare class BackupCycle {
     private reportSkip;
     private tick;
     private verifyChain;
+    /** Drops the chain that this stopped cycle extended, so that the next cycle starts a new chain with a full copy. */
+    forgetChain(): Promise<void>;
     private discardState;
     /**
      * Runs one turn. When the turn fails with `BACKUP_LOG_REWOUND` or
@@ -784,6 +792,101 @@ declare class BackupCycle {
     private sendWaitingCapture;
 }
 
+/**
+ * The key that an {@link EncryptionOptions.key} function returns: 32 raw bytes, or those bytes with an identifier that
+ * Sirannon stores in the database and reports through {@link EncryptionStatus.keyId}.
+ *
+ * @public
+ */
+type EncryptionKey = Uint8Array | {
+    key: Uint8Array;
+    id?: string;
+};
+/**
+ * Settings that encrypt every page of a database file, its write-ahead log, and every backup that Sirannon writes for
+ * it.
+ *
+ * @public
+ */
+interface EncryptionOptions {
+    /**
+     * Returns the 32-byte key. Sirannon calls it each time it opens the database's connections, which includes a
+     * restarted writer worker and the reopen after a restore or a key change, so the key can come from a key service or
+     * a keychain. Sirannon copies the bytes and wipes its copy once those connections are open, so the function can
+     * return a buffer that it keeps.
+     */
+    key: () => EncryptionKey | Promise<EncryptionKey>;
+}
+/**
+ * The key change that {@link DatabaseEncryption.changeEncryption} makes: a `key` function encrypts a plaintext database or
+ * changes the key of an encrypted one, and `null` removes encryption.
+ *
+ * @public
+ */
+interface EncryptionChange {
+    /** Returns the 32-byte key that the database takes, or `null` to store the database as plaintext. */
+    key: (() => EncryptionKey | Promise<EncryptionKey>) | null;
+}
+/**
+ * The progress of the current key change, or the outcome of the last one.
+ *
+ * @public
+ */
+interface EncryptionChangeStatus {
+    /**
+     * `idle` before any change, `copying` while Sirannon copies a snapshot to the new file, `catching-up` while it
+     * applies the writes committed since that snapshot, `swapping` while it holds writes and replaces the file, and
+     * `done` or `failed` once the change ends.
+     */
+    state: 'idle' | 'copying' | 'catching-up' | 'swapping' | 'done' | 'failed';
+    /** Whether the change encrypts the file or stores it as plaintext. */
+    target?: 'encrypted' | 'plaintext';
+    /** The time at which the change started, in milliseconds since the Unix epoch. */
+    startedAt?: number;
+    /** The time at which the change ended, in milliseconds since the Unix epoch. */
+    finishedAt?: number;
+    /** The number of rows that the snapshot copy wrote to the new file. */
+    rowsCopied?: number;
+    /** The number of rounds in which Sirannon applied the writes committed since the snapshot. */
+    rounds?: number;
+    /** The code and message of the error that stopped the change. */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * The code and message of an error that came after the new file was in place, such as a key function that failed
+     * when the connections reopened. The change is `done` and the file holds ciphertext under the new key, so keep that
+     * key, and close and open the database again with it.
+     */
+    reopenError?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Reports whether a database is encrypted, under which key, and how its last key change went.
+ *
+ * @public
+ */
+interface EncryptionStatus {
+    /** Whether the database file holds ciphertext. */
+    encrypted: boolean;
+    /**
+     * The scheme that an encrypted file uses: `aegis-256` from the better-sqlite3 driver, or `sqlcipher-4` from the
+     * Expo driver.
+     */
+    cipher?: 'aegis-256' | 'sqlcipher-4';
+    /** The version of the encryption engine, which an encrypted database reports. */
+    cipherVersion?: string;
+    /** The identifier that came with the current key. */
+    keyId?: string;
+    /** The time at which the last key change finished, in milliseconds since the Unix epoch. */
+    changedAt?: number;
+    /** The current key change, or the last one. */
+    change: EncryptionChangeStatus;
+}
+
 /** The context that Sirannon passes to each query hook.
  * @public
  */
@@ -1318,6 +1421,14 @@ interface DatabaseOptions {
      * off.
      */
     backups?: BackupCycleOptions;
+    /**
+     * Encrypts every page of the database file, its write-ahead log, and every
+     * backup that Sirannon writes for it, under a 32-byte key that your function
+     * returns. The driver has to report `encryption` in its capabilities, and with
+     * any other driver the open throws `ENCRYPTION_UNSUPPORTED`. The default is
+     * off, which keeps the file as plaintext.
+     */
+    encryption?: EncryptionOptions;
 }
 /** The limits and recovery settings for the writer worker thread.
  * @public
@@ -1422,6 +1533,45 @@ interface WorkerHostOptions {
     writeTimeoutMs?: number;
     maxRestarts?: number;
     countsRows?: boolean;
+    encryptionKey?: () => Promise<Uint8Array>;
+}
+
+/**
+ * The file operations that a key change and its recovery perform on a database's files, which a driver for a runtime
+ * with a file system supplies.
+ *
+ * When the runtime lacks a module that the operations need, each one can throw an `EncryptionError` with
+ * `ENCRYPTION_UNSUPPORTED`. A key change then stops before it writes any file, and an open finds no key change to
+ * finish.
+ *
+ * @public
+ */
+interface DatabaseFileSystem {
+    /**
+     * Returns the first bytes of a file, fewer when the file is shorter.
+     *
+     * @param path - The file to read.
+     * @param length - The most bytes to return.
+     * @returns The bytes, or `null` when the file does not exist.
+     */
+    readStart(path: string, length: number): Promise<Uint8Array | null>;
+    /**
+     * Deletes a file, and resolves without an error when the file does not exist.
+     *
+     * @param path - The file to delete.
+     */
+    remove(path: string): Promise<void>;
+    /**
+     * Moves a file to a new path in the same directory, replacing any file at that path.
+     *
+     * Where the file system replaces a file in one rename, the move takes that one step. Where it cannot, the move
+     * deletes the file at the new path and then renames the file, so a crash between the two steps can leave neither
+     * file at the new path. Sirannon recovers from that state on the next open.
+     *
+     * @param from - The file to move.
+     * @param to - The path that the file takes.
+     */
+    rename(from: string, to: string): Promise<void>;
 }
 
 /** Describes the result of one write through the driver.
@@ -1659,6 +1809,28 @@ interface SQLiteConnection {
     runGroup?(units: readonly {
         statements: readonly GroupRunStatement[];
     }[], opening?: GroupRunStatement): Promise<GroupRunOutcome[]>;
+    /**
+     * Starts recording every row that later writes on this connection insert,
+     * update, or delete in the main database, through SQLite's session extension.
+     * Sirannon calls it on the writer while it holds the writer, at the instant
+     * that a key change copies its snapshot, so the snapshot and the recording
+     * start from the same committed state.
+     */
+    startChangeCapture?(): Promise<void>;
+    /**
+     * Returns the rows that changed since the recording started or since the
+     * last call, as a SQLite changeset, and restarts the recording in the same
+     * step. Call it only while no transaction is open on the connection.
+     */
+    takeCapturedChanges?(): Promise<Uint8Array>;
+    /** Stops the recording that {@link SQLiteConnection.startChangeCapture} started, and drops what it holds. */
+    stopChangeCapture?(): Promise<void>;
+    /**
+     * Applies a changeset from {@link SQLiteConnection.takeCapturedChanges} to
+     * this connection's database with triggers off, and fails without applying
+     * any of it when a change does not match the rows that it expects.
+     */
+    applyCapturedChanges?(changes: Uint8Array): Promise<void>;
 }
 /**
  * The SQLite `PRAGMA synchronous` level for a connection. In WAL mode,
@@ -1692,6 +1864,15 @@ interface OpenOptions {
      * open, including after a writer worker restarts.
      */
     walAutoCheckpoint?: number;
+    /**
+     * The 32-byte key of an encrypted database. Sirannon sets it on every open
+     * of an encrypted database, and the driver keeps no reference to the key once
+     * `open` returns. A driver whose capabilities report `encryption` as false
+     * fails such an open with `ENCRYPTION_UNSUPPORTED`.
+     */
+    encryption?: {
+        key: Uint8Array;
+    };
 }
 /** Describes what a driver's runtime supports.
  * @public
@@ -1710,6 +1891,11 @@ interface DriverCapabilities {
      * {@link SQLiteStatement.allCounted}.
      */
     rowCounts: boolean;
+    /**
+     * `true` when the driver encrypts every page of the database file and its
+     * log under the 32-byte key that {@link OpenOptions.encryption} carries.
+     */
+    encryption: boolean;
 }
 /**
  * Describes how a worker thread rebuilds the driver, since a function such as
@@ -1758,6 +1944,8 @@ interface SQLiteDriver {
      * different library from the one that the operator named.
      */
     resolveExtensionPath?(extensionPath: string): string;
+    /** The file operations that a key change and its recovery perform, which a driver for a runtime with a file system supplies. */
+    readonly files?: DatabaseFileSystem;
 }
 
-export { type BatchSummary as $, type AfterQueryHook as A, type BackupDestination as B, type BackupVerifyResult as C, type DatabaseOptions as D, DEFAULT_CHAIN_NAME as E, chainLogName as F, readBackupChains as G, verifyBackupRecord as H, type ClusterStatusInfo as I, type SQLiteConnection as J, type BackupFileCopy as K, type BackupRunRequest as L, type Migration as M, type NodeHealth as N, type BackupScheduleRequest as O, type BackupScheduleOptions as P, type DriverCapabilities as Q, type RunExclusive as R, type SQLiteDriver as S, Transaction as T, type BackupEngine as U, type SynchronousLevel as V, type LifecycleConfig as W, type MigrationResult as X, type RollbackResult as Y, type AfterQueryHookContext as Z, type AppliedMigrationEntry as _, type SirannonOptions as a, type BeforePushHook as a0, type BeforeSnapshotHook as a1, type BeforeSubscribeHook as a2, type CDCMetrics as a3, type ClusterReadEndpointInfo as a4, type ConnectionHookContext as a5, type ConnectionMetrics as a6, type Counted as a7, type DatabaseCopyRequest as a8, type DatabaseCopyStep as a9, type DriverWorkerEntry as aa, type HookConfig as ab, MIGRATION_NAME_RE as ac, type MetricsConfig as ad, type MigrationBaseline as ae, type MigrationSource as af, NODE_HEALTH_REASONS as ag, NODE_HEALTH_STATES as ah, type NodeHealthReason as ai, type NodeHealthState as aj, type OpenOptions as ak, type QueryHookContext as al, type QueryMetrics as am, type RunResult as an, type SQLiteStatement as ao, type WriterWorkerOptions as ap, type WorkerHostOptions as aq, type ChangeDispatchObserver as ar, SubscriptionManager as as, type WriterTransactionRunner as at, type StatementMeter as au, type WriterContext as av, type QueryOutcomeMeasure as aw, type QueryFailureMeasure as ax, type QueryOutcome as ay, type RowCounts as az, MetricsCollector as b, type BeforeQueryHook as c, type BeforeConnectHook as d, type DatabaseOpenHook as e, type DatabaseCloseHook as f, type BackupRunReport as g, type BackupChain as h, type BackupChainBase as i, type BackupChainChange as j, type BackupChainPosition as k, type BackupChainRecord as l, BackupCycle as m, type BackupCycleError as n, type BackupCycleOptions as o, type BackupCycleStatus as p, type BackupFileReport as q, type BackupGroupMembership as r, type BackupGroupSource as s, type BackupLogPosition as t, type BackupNodePreference as u, type BackupPiece as v, type BackupProgress as w, type BackupSkip as x, type BackupSkipReason as y, type BackupToDestinationOptions as z };
+export { type AfterQueryHookContext as $, type AfterQueryHook as A, type BackupDestination as B, type BackupVerifyResult as C, type DatabaseOptions as D, type EncryptionOptions as E, DEFAULT_CHAIN_NAME as F, chainLogName as G, readBackupChains as H, verifyBackupRecord as I, type EncryptionKey as J, type ClusterStatusInfo as K, type SQLiteConnection as L, type Migration as M, type NodeHealth as N, type BackupFileCopy as O, type BackupRunRequest as P, type BackupScheduleRequest as Q, type BackupScheduleOptions as R, type SQLiteDriver as S, Transaction as T, type RunExclusive as U, type DriverCapabilities as V, type BackupEngine as W, type SynchronousLevel as X, type LifecycleConfig as Y, type MigrationResult as Z, type RollbackResult as _, type SirannonOptions as a, type AppliedMigrationEntry as a0, type BatchSummary as a1, type BeforePushHook as a2, type BeforeSnapshotHook as a3, type BeforeSubscribeHook as a4, type CDCMetrics as a5, type ClusterReadEndpointInfo as a6, type ConnectionHookContext as a7, type ConnectionMetrics as a8, type Counted as a9, type StatementMeter as aA, type WriterContext as aB, type QueryOutcomeMeasure as aC, type QueryFailureMeasure as aD, type QueryOutcome as aE, type RowCounts as aF, type DatabaseCopyRequest as aa, type DatabaseCopyStep as ab, type DatabaseFileSystem as ac, type DriverWorkerEntry as ad, type EncryptionChange as ae, type EncryptionChangeStatus as af, type EncryptionStatus as ag, type HookConfig as ah, MIGRATION_NAME_RE as ai, type MetricsConfig as aj, type MigrationBaseline as ak, type MigrationSource as al, NODE_HEALTH_REASONS as am, NODE_HEALTH_STATES as an, type NodeHealthReason as ao, type NodeHealthState as ap, type OpenOptions as aq, type QueryHookContext as ar, type QueryMetrics as as, type RunResult as at, type SQLiteStatement as au, type WriterWorkerOptions as av, type WorkerHostOptions as aw, type ChangeDispatchObserver as ax, SubscriptionManager as ay, type WriterTransactionRunner as az, MetricsCollector as b, type BeforeQueryHook as c, type BeforeConnectHook as d, type DatabaseOpenHook as e, type DatabaseCloseHook as f, type BackupRunReport as g, type BackupChain as h, type BackupChainBase as i, type BackupChainChange as j, type BackupChainPosition as k, type BackupChainRecord as l, BackupCycle as m, type BackupCycleError as n, type BackupCycleOptions as o, type BackupCycleStatus as p, type BackupFileReport as q, type BackupGroupMembership as r, type BackupGroupSource as s, type BackupLogPosition as t, type BackupNodePreference as u, type BackupPiece as v, type BackupProgress as w, type BackupSkip as x, type BackupSkipReason as y, type BackupToDestinationOptions as z };