@delali/sirannon-sqlite 0.3.6-next.77 → 0.3.6-next.78

package/NOTICE

@@ -38,9 +38,25 @@ This product includes code from these projects:
   2017 Node.js API collaborators, licensed under the MIT License. Each
   @delali/sirannon-sqlite-<platform> package contains code compiled from
   node-addon-api's headers.
+- SQLite3 Multiple Ciphers
+  (https://github.com/utelle/SQLite3MultipleCiphers), Copyright (c) 2006-2026
+  Ulrich Telle, licensed under the MIT License. Each
+  @delali/sirannon-sqlite-<platform> package contains SQLite3 Multiple
+  Ciphers compiled from its amalgamation, with the patches in
+  native/sqlite/patches/sqlite applied. That amalgamation also contains the
+  code in the next three entries.
+- The AEGIS library, Copyright (c) 2023-2024 Frank Denis, licensed under the
+  MIT License, which SQLite3 Multiple Ciphers carries for its AEGIS cipher.
+- The FIPS 180-2 SHA-224/256/384/512 implementation, Copyright (C) 2005, 2007
+  Olivier Gay, licensed under the BSD 3-Clause License.
+- The Argon2 reference implementation, Copyright 2015 Daniel Dinu, Dmitry
+  Khovratovich, Jean-Philippe Aumasson, and Samuel Neves, which its authors
+  offer under CC0 1.0 or the Apache License, Version 2.0. Sirannon uses it
+  under the Apache License, Version 2.0.
 
 The MIT License grants the following permission for libSQL, node-gyp,
-better-sqlite3, and node-addon-api:
+better-sqlite3, node-addon-api, SQLite3 Multiple Ciphers, and the AEGIS
+library:
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -59,3 +75,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+The BSD 3-Clause License grants the following permission for the FIPS 180-2
+SHA-224/256/384/512 implementation:
+
+Copyright (C) 2005, 2007 Olivier Gay <olivier.gay@a3.epfl.ch>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the project nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@delali/sirannon-sqlite)](https://www.npmjs.com/package/@delali/sirannon-sqlite)
 [![license](https://img.shields.io/npm/l/@delali/sirannon-sqlite)](https://github.com/assetcorp/sirannon-db/blob/main/LICENSE)
 
-This package contains better-sqlite3 13.0.2, built against Sirannon's own build of SQLite, which counts the rows that each statement reads and writes. When you pass `rowCounts: true`, Sirannon's better-sqlite3 driver loads this package and reports both counts for every statement through `onQueryComplete`, so that a host that puts many tenants on one machine can bill each of them.
+This package contains better-sqlite3 13.0.2, built against Sirannon's build of SQLite, which is SQLite3 Multiple Ciphers with a patch that counts the rows that each statement reads and writes. When you pass `rowCounts: true`, Sirannon's better-sqlite3 driver loads this package and reports both counts for every statement through `onQueryComplete`, so that a host that puts many tenants on one machine can bill each of them. When you pass `encryption: true`, the driver loads this package and keeps every page of a database that you open with the `encryption` option as ciphertext, as the [encryption guide](https://github.com/assetcorp/sirannon-db/blob/main/docs/encryption.md) describes.
 
 ## Install
 
@@ -21,16 +21,23 @@ const sirannon = new Sirannon({
   driver: betterSqlite3({ rowCounts: true }),
   metrics: { onQueryComplete: m => console.log(m.databaseId, m.rowsRead, m.rowsWritten) },
 })
+
+const encrypting = new Sirannon({ driver: betterSqlite3({ encryption: true }) })
+const ledger = await encrypting.open('ledger', './ledger.db', { encryption: { key: loadLedgerKey } })
 ```
 
+`loadLedgerKey` stands for a function of yours that returns the 32 key bytes from a key service or a keychain.
+
 This package lists six platform packages as optional dependencies, so npm installs only the one whose `os` and `cpu` match your host. The release workflow publishes all seven packages at the library's version, and this package requires exactly that version of each platform package.
 
 ## What it contains
 
-The `lib` directory contains better-sqlite3's JavaScript, unchanged. Sirannon compiles the native module from better-sqlite3's C++ source and the SQLite amalgamation, after it applies each patch in the repository's `native/sqlite/patches` directory. The first SQLite patch is Cloudflare's row-counting patch, which Sirannon changed to widen both counters to 64 bits and to leave the work of its own change-capture triggers out of both counts, and the first better-sqlite3 patch adds the `takeRowCounts` method that reads them. The counting rules are in the [core engine guide](https://github.com/assetcorp/sirannon-db/blob/main/docs/core.md#rows-read-and-rows-written).
+The `lib` directory contains better-sqlite3's JavaScript, unchanged. Sirannon compiles the native module from better-sqlite3's C++ source and the SQLite3 Multiple Ciphers 2.6.1 amalgamation, which carries SQLite 3.54.0, after it applies each patch in the repository's `native/sqlite/patches` directory. The first SQLite patch is Cloudflare's row-counting patch, which Sirannon changed to widen both counters to 64 bits and to leave the work of its own change-capture triggers out of both counts, and the first better-sqlite3 patch adds the `takeRowCounts` method that reads them. The counting rules are in the [core engine guide](https://github.com/assetcorp/sirannon-db/blob/main/docs/core.md#rows-read-and-rows-written).
+
+The second SQLite patch adds the `sirannon_export` function, which copies the main database into an attached database under that database's key and keeps the rowid of every row, as `VACUUM INTO` does. The second better-sqlite3 patch adds the `key` method that hands SQLite3 Multiple Ciphers a raw 32-byte key, keys the destination of a backup with the source's key, and adds the calls that record a connection's changes through SQLite's session extension, so that a key change can apply the writes that commit while it copies the file. SQLite3 Multiple Ciphers encrypts each page with AEGIS-256, from code that is compiled into the native module.
 
-On a platform without a published build, the driver throws `ROW_COUNTS_UNSUPPORTED` when it opens a database. Compile a build with `native/sqlite/build.mjs` from the repository, and pass its path to the driver as `sqliteBindingPath`.
+On a platform without a published build, the driver throws `ROW_COUNTS_UNSUPPORTED` or `ENCRYPTION_UNSUPPORTED` when it opens a database. Compile a build with `native/sqlite/build.mjs` from the repository, and pass its path to the driver as `sqliteBindingPath`.
 
 ## Licence
 
-The Apache-2.0 and MIT licences cover this package. Each project whose code is in this package has its name and licence in the package's `NOTICE` file, and the patches, the build script, and the tests are in [assetcorp/sirannon-db](https://github.com/assetcorp/sirannon-db).
+The Apache-2.0 and MIT licences cover this package, and the BSD-3-Clause licence also covers each platform package, since the SQLite3 Multiple Ciphers amalgamation in those carries a SHA-2 implementation under that licence. Each project whose code is in this package has its name and licence in the package's `NOTICE` file, and the patches, the build script, and the tests are in [assetcorp/sirannon-db](https://github.com/assetcorp/sirannon-db).

package/index.d.ts

@@ -1,6 +1,20 @@
 import BetterSqlite3 = require('better-sqlite3')
 
-declare const Database: typeof BetterSqlite3 & {
+declare namespace Database {
+  interface SirannonDatabase extends BetterSqlite3.Database {
+    key(rawKey: Uint8Array): this
+    startChangeCapture(): this
+    takeCapturedChanges(): Buffer
+    stopChangeCapture(): this
+    applyChanges(changes: Uint8Array): this
+  }
+}
+
+declare const Database: {
+  new (filename?: string | Buffer, options?: BetterSqlite3.Options): Database.SirannonDatabase
+  (filename?: string | Buffer, options?: BetterSqlite3.Options): Database.SirannonDatabase
+  prototype: Database.SirannonDatabase
+  SqliteError: typeof BetterSqlite3.SqliteError
   bindingPath(): string | null
 }
 

package/index.js

@@ -2,6 +2,7 @@ const { existsSync } = require('node:fs')
 const { dirname, join, resolve } = require('node:path')
 const createDatabase = require('./lib/database')
 const SqliteError = require('./lib/sqlite-error')
+const { cppdb } = require('./lib/util')
 
 const ADDON_FILE_NAME = 'better_sqlite3.node'
 const MUSL_DIRECTORY = 'musl'
@@ -54,6 +55,32 @@ function loadAddon(nativeBinding) {
   return require(path)
 }
 
-module.exports = createDatabase(loadAddon, true)
+const Database = createDatabase(loadAddon, true)
+
+Database.prototype.key = function key(rawKey) {
+  this[cppdb].key(rawKey)
+  return this
+}
+
+Database.prototype.startChangeCapture = function startChangeCapture() {
+  this[cppdb].startChangeCapture()
+  return this
+}
+
+Database.prototype.takeCapturedChanges = function takeCapturedChanges() {
+  return this[cppdb].takeCapturedChanges()
+}
+
+Database.prototype.stopChangeCapture = function stopChangeCapture() {
+  this[cppdb].stopChangeCapture()
+  return this
+}
+
+Database.prototype.applyChanges = function applyChanges(changes) {
+  this[cppdb].applyChanges(changes)
+  return this
+}
+
+module.exports = Database
 module.exports.SqliteError = SqliteError
 module.exports.bindingPath = bindingPath

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@delali/sirannon-sqlite",
-  "version": "0.3.6-next.77",
-  "description": "better-sqlite3 built against Sirannon's build of SQLite, which counts the rows that each statement reads and writes so that Sirannon can report them for per-tenant metering.",
+  "version": "0.3.6-next.78",
+  "description": "better-sqlite3 built against Sirannon's build of SQLite3 Multiple Ciphers, which encrypts every page of a database with AEGIS-256 under a 32-byte key and counts the rows that each statement reads and writes so that Sirannon can report them for per-tenant metering.",
   "license": "Apache-2.0 AND MIT",
   "author": "Delali (https://sondelali.com)",
   "homepage": "https://github.com/assetcorp/sirannon-db",
@@ -33,11 +33,11 @@
     "@types/better-sqlite3": "7.6.13"
   },
   "optionalDependencies": {
-    "@delali/sirannon-sqlite-darwin-arm64": "0.3.6-next.77",
-    "@delali/sirannon-sqlite-darwin-x64": "0.3.6-next.77",
-    "@delali/sirannon-sqlite-linux-arm64": "0.3.6-next.77",
-    "@delali/sirannon-sqlite-linux-x64": "0.3.6-next.77",
-    "@delali/sirannon-sqlite-win32-arm64": "0.3.6-next.77",
-    "@delali/sirannon-sqlite-win32-x64": "0.3.6-next.77"
+    "@delali/sirannon-sqlite-darwin-arm64": "0.3.6-next.78",
+    "@delali/sirannon-sqlite-darwin-x64": "0.3.6-next.78",
+    "@delali/sirannon-sqlite-linux-arm64": "0.3.6-next.78",
+    "@delali/sirannon-sqlite-linux-x64": "0.3.6-next.78",
+    "@delali/sirannon-sqlite-win32-arm64": "0.3.6-next.78",
+    "@delali/sirannon-sqlite-win32-x64": "0.3.6-next.78"
   }
 }