@monlite/core 0.10.0 → 1.1.0

package/dist/index.d.cts

@@ -357,12 +357,28 @@ interface GroupByArgs<T = Doc> {
 }
 type GroupByResult = Record<string, any>;
 type DriverName = "auto" | "better-sqlite3" | "node:sqlite";
+/** Encryption-at-rest configuration (requires `better-sqlite3-multiple-ciphers`). */
+interface EncryptionOptions {
+    /** The passphrase used to encrypt/decrypt the database file. */
+    key: string;
+    /**
+     * Cipher scheme to use (e.g. `"sqlcipher"`, `"chacha20"`, `"aes256cbc"`).
+     * Defaults to the library default (ChaCha20-Poly1305).
+     */
+    cipher?: string;
+}
 interface MonliteOptions {
     /**
      * Which SQLite backend to use. `"auto"` (default) prefers `better-sqlite3`
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
      */
     driver?: DriverName;
+    /**
+     * Encrypt the database at rest. Requires the `better-sqlite3-multiple-ciphers`
+     * package (a drop-in for `better-sqlite3`); not supported on `node:sqlite`.
+     * Use `db.rekey(newKey)` to rotate the key.
+     */
+    encryption?: EncryptionOptions;
     /** Opt-in plugins (e.g. `@monlite/fts`). */
     plugins?: MonlitePlugin[];
     /**
@@ -414,6 +430,8 @@ interface Driver {
     /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
     transaction<T>(fn: () => T): T;
     close(): void;
+    /** Rotate the encryption key (encrypted backends only). */
+    rekey?(key: string, cipher?: string): void;
     /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
     readonly raw: any;
 }
@@ -613,6 +631,7 @@ declare class Monlite {
     readonly $sync?: SyncStore;
     private readonly collections;
     private readonly plugins;
+    private readonly encrypted;
     private closed;
     constructor(filename: string, options?: MonliteOptions);
     /** @internal Notify plugins that documents changed (post-commit). */
@@ -655,6 +674,11 @@ declare class Monlite {
      * `VACUUM INTO`). The destination file must not already exist.
      */
     backup(path: string): Promise<void>;
+    /**
+     * Rotate the encryption key. Only valid for a database opened with the
+     * `encryption` option; throws otherwise. Pass `cipher` to also change scheme.
+     */
+    rekey(key: string, cipher?: string): void;
     /** Close the underlying SQLite connection. */
     $disconnect(): Promise<void>;
     private assertOpen;
@@ -677,6 +701,12 @@ declare class MonliteQueryError extends MonliteError {
         cause?: unknown;
     });
 }
+/** Thrown when an encrypted database can't be opened (wrong key, not encrypted). */
+declare class MonliteEncryptionError extends MonliteError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /** A database constraint was violated (base class for the specific kinds). */
 declare class MonliteConstraintError extends MonliteError {
     readonly collection?: string;
@@ -717,4 +747,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.d.ts

@@ -357,12 +357,28 @@ interface GroupByArgs<T = Doc> {
 }
 type GroupByResult = Record<string, any>;
 type DriverName = "auto" | "better-sqlite3" | "node:sqlite";
+/** Encryption-at-rest configuration (requires `better-sqlite3-multiple-ciphers`). */
+interface EncryptionOptions {
+    /** The passphrase used to encrypt/decrypt the database file. */
+    key: string;
+    /**
+     * Cipher scheme to use (e.g. `"sqlcipher"`, `"chacha20"`, `"aes256cbc"`).
+     * Defaults to the library default (ChaCha20-Poly1305).
+     */
+    cipher?: string;
+}
 interface MonliteOptions {
     /**
      * Which SQLite backend to use. `"auto"` (default) prefers `better-sqlite3`
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
      */
     driver?: DriverName;
+    /**
+     * Encrypt the database at rest. Requires the `better-sqlite3-multiple-ciphers`
+     * package (a drop-in for `better-sqlite3`); not supported on `node:sqlite`.
+     * Use `db.rekey(newKey)` to rotate the key.
+     */
+    encryption?: EncryptionOptions;
     /** Opt-in plugins (e.g. `@monlite/fts`). */
     plugins?: MonlitePlugin[];
     /**
@@ -414,6 +430,8 @@ interface Driver {
     /** Run `fn` inside a transaction; rolls back and rethrows if it throws. */
     transaction<T>(fn: () => T): T;
     close(): void;
+    /** Rotate the encryption key (encrypted backends only). */
+    rekey?(key: string, cipher?: string): void;
     /** The underlying native handle (better-sqlite3 Database / node:sqlite DatabaseSync). */
     readonly raw: any;
 }
@@ -613,6 +631,7 @@ declare class Monlite {
     readonly $sync?: SyncStore;
     private readonly collections;
     private readonly plugins;
+    private readonly encrypted;
     private closed;
     constructor(filename: string, options?: MonliteOptions);
     /** @internal Notify plugins that documents changed (post-commit). */
@@ -655,6 +674,11 @@ declare class Monlite {
      * `VACUUM INTO`). The destination file must not already exist.
      */
     backup(path: string): Promise<void>;
+    /**
+     * Rotate the encryption key. Only valid for a database opened with the
+     * `encryption` option; throws otherwise. Pass `cipher` to also change scheme.
+     */
+    rekey(key: string, cipher?: string): void;
     /** Close the underlying SQLite connection. */
     $disconnect(): Promise<void>;
     private assertOpen;
@@ -677,6 +701,12 @@ declare class MonliteQueryError extends MonliteError {
         cause?: unknown;
     });
 }
+/** Thrown when an encrypted database can't be opened (wrong key, not encrypted). */
+declare class MonliteEncryptionError extends MonliteError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /** A database constraint was violated (base class for the specific kinds). */
 declare class MonliteConstraintError extends MonliteError {
     readonly collection?: string;
@@ -717,4 +747,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.js

@@ -116,6 +116,12 @@ var MonliteQueryError = class extends MonliteError {
     this.name = "MonliteQueryError";
   }
 };
+var MonliteEncryptionError = class extends MonliteError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteEncryptionError";
+  }
+};
 var MonliteConstraintError = class extends MonliteError {
   collection;
   constructor(message, options) {
@@ -1314,6 +1320,7 @@ var AutoIndexer = class {
 
 // src/driver/better-sqlite3.ts
 var STMT_CACHE_MAX = 256;
+var quote = (s) => s.replace(/'/g, "''");
 var BetterSqlite3Driver = class {
   name = "better-sqlite3";
   raw;
@@ -1324,6 +1331,9 @@ var BetterSqlite3Driver = class {
     this.raw = new BetterSqlite3(filename, {
       readonly: options.readonly ?? false
     });
+    if (options.encryption) {
+      this.applyKey(options.encryption.key, options.encryption.cipher);
+    }
     this.raw.pragma("foreign_keys = ON");
     this.raw.pragma(`busy_timeout = ${options.busyTimeout ?? 5e3}`);
     if (!options.readonly && (options.wal ?? true)) {
@@ -1352,6 +1362,28 @@ var BetterSqlite3Driver = class {
   transaction(fn) {
     return this.raw.transaction(fn)();
   }
+  /** Apply the encryption key and verify it by reading the schema. */
+  applyKey(key, cipher) {
+    if (cipher) this.raw.pragma(`cipher='${quote(cipher)}'`);
+    this.raw.pragma(`key='${quote(key)}'`);
+    try {
+      this.raw.exec("SELECT count(*) FROM sqlite_master");
+    } catch (err) {
+      this.raw.close();
+      throw new MonliteEncryptionError(
+        "Failed to open the encrypted database: the key is incorrect, or the file is not encrypted.",
+        { cause: err }
+      );
+    }
+  }
+  rekey(key, cipher) {
+    if (cipher) this.raw.pragma(`cipher='${quote(cipher)}'`);
+    const mode = String(this.raw.pragma("journal_mode", { simple: true }));
+    const wasWal = mode.toLowerCase() === "wal";
+    if (wasWal) this.raw.pragma("journal_mode = DELETE");
+    this.raw.pragma(`rekey='${quote(key)}'`);
+    if (wasWal) this.raw.pragma("journal_mode = WAL");
+  }
   close() {
     this.cache.clear();
     this.raw.close();
@@ -1367,6 +1399,11 @@ var NodeSqliteDriver = class {
   cache = /* @__PURE__ */ new Map();
   depth = 0;
   constructor(nodeSqlite, filename, options) {
+    if (options.encryption) {
+      throw new MonliteError(
+        "Encryption is not supported on the node:sqlite backend. Use better-sqlite3 with the better-sqlite3-multiple-ciphers package."
+      );
+    }
     this.verbose = options.verbose;
     const { DatabaseSync } = nodeSqlite;
     this.raw = new DatabaseSync(filename, {
@@ -1442,6 +1479,14 @@ function loadBetterSqlite3() {
     return null;
   }
 }
+function loadCipherSqlite3() {
+  try {
+    const mod = req("better-sqlite3-multiple-ciphers");
+    return mod?.default ?? mod;
+  } catch {
+    return null;
+  }
+}
 function loadNodeSqlite() {
   try {
     return req("node:sqlite");
@@ -1451,6 +1496,20 @@ function loadNodeSqlite() {
 }
 function createDriver(filename, options = {}) {
   const choice = options.driver ?? "auto";
+  if (options.encryption) {
+    if (choice === "node:sqlite") {
+      throw new MonliteError(
+        `Encryption is not supported on the node:sqlite backend. Use better-sqlite3 with the better-sqlite3-multiple-ciphers package.`
+      );
+    }
+    const cipher = loadCipherSqlite3();
+    if (!cipher) {
+      throw new MonliteError(
+        `Encryption requires the "better-sqlite3-multiple-ciphers" package (a drop-in for better-sqlite3). Run \`npm install better-sqlite3-multiple-ciphers\`.`
+      );
+    }
+    return new BetterSqlite3Driver(cipher, filename, options);
+  }
   if (choice === "better-sqlite3") {
     const mod = loadBetterSqlite3();
     if (!mod) {
@@ -1890,6 +1949,7 @@ var Monlite = class {
   $sync;
   collections = /* @__PURE__ */ new Map();
   plugins;
+  encrypted;
   closed = false;
   constructor(filename, options = {}) {
     this.driver = createDriver(filename, {
@@ -1898,8 +1958,10 @@ var Monlite = class {
       wal: options.wal,
       busyTimeout: options.busyTimeout,
       allowExtensions: options.allowExtensions,
+      encryption: options.encryption,
       verbose: options.verbose
     });
+    this.encrypted = options.encryption !== void 0;
     this.autoIndexer = new AutoIndexer(
       this.driver,
       options.autoIndex ?? true,
@@ -2047,6 +2109,19 @@ var Monlite = class {
     this.driver.exec(`VACUUM INTO '${path.replace(/'/g, "''")}'`);
     return Promise.resolve();
   }
+  /**
+   * Rotate the encryption key. Only valid for a database opened with the
+   * `encryption` option; throws otherwise. Pass `cipher` to also change scheme.
+   */
+  rekey(key, cipher) {
+    this.assertOpen();
+    if (!this.encrypted || !this.driver.rekey) {
+      throw new MonliteError(
+        "rekey() requires a database opened with the `encryption` option."
+      );
+    }
+    this.driver.rekey(key, cipher);
+  }
   /** Close the underlying SQLite connection. */
   $disconnect() {
     if (!this.closed) {
@@ -2063,6 +2138,6 @@ function createDb(filename, options) {
   return new Monlite(filename, options);
 }
 
-export { Collection, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, MonliteQueryError, MonliteUniqueConstraintError, SyncStore, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { Collection, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, MonliteQueryError, MonliteUniqueConstraintError, SyncStore, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map