@evolu/sqlite-wasm 2.2.4 → 3.53.4-build1

package/dist/src/Database.d.ts

@@ -0,0 +1,641 @@
+/**
+ * Evolu's SQLite API: databases and statements over the CApi functions, with
+ * typed errors and explicit resource management.
+ *
+ * Status: {@link createSqliteDatabase} opens Memory databases, and File and
+ * EncryptedFile databases on a {@link SqliteVfs} or {@link SqliteEncryptingVfs},
+ * which a {@link SahPool} is, and {@link createEncryptedSqliteDatabase} also
+ * opens the encrypted databases `@evolu/web` 3 created with
+ * `@evolu/sqlite-wasm` 2.2.4 in a pool. The pool's own encryption is tested in
+ * Node.js over a fake OPFS against 2.2.4, which creates databases as
+ * `@evolu/web` does and leaves a hot journal the pool rolls back, and in
+ * Chromium, Firefox and WebKit on real OPFS against 2.2.4.
+ *
+ * ## Calls
+ *
+ * - Synchronous. Every call returns when SQLite returns. The only asynchronous
+ *   step, deriving a legacy key with WebCrypto, runs between the two opens of
+ *   {@link createEncryptedSqliteDatabase}.
+ * - Bound once per database. {@link createSqliteDatabase} binds the C functions
+ *   and memory helpers it needs and allocates one {@link SqliteScratch}; running
+ *   a statement then calls wasm exports directly.
+ * - Every fallible call returns a Result. {@link SqliteError} copies
+ *   `sqlite3_errmsg` and `sqlite3_extended_errcode` right after the failing
+ *   call, before any other call on the connection replaces them. It copies
+ *   `sqlite3_error_offset` only for SQLITE_ERROR from prepare, exec or step,
+ *   the code of the parser errors that set it, because SQLite keeps an offset
+ *   until a later prepare succeeds or a statement resets.
+ * - The VFS records the first failure since the last top-level call (open,
+ *   prepare, run, exec, export), and {@link SqliteError.cause} carries it. The
+ *   database clears the record before each such call. A call that runs inside
+ *   another call of a database on the same VFS, as a query a callback runs
+ *   does, is not top-level, so it leaves the record to the outer call.
+ * - Every call, disposal included, enters wasm through {@link SqliteWasm.call}. An
+ *   exception or trap that escapes wasm, such as from a call through a disposed
+ *   function pointer, is a defect: it is rethrown, and every later call on any
+ *   database of the instance throws without entering wasm, because the C stack
+ *   and SQLite's state are left inconsistent. A trap after a File or
+ *   EncryptedFile connection opened reaches the caller of the open as a
+ *   `SuppressedError` whose `suppressed` is the trap, because the open's
+ *   deferred close and the free of its scratch memory are refused as it
+ *   unwinds.
+ *
+ * ## Opening
+ *
+ * - A Memory database opens `:memory:` on the default VFS.
+ * - A File or EncryptedFile database's path is a {@link SqliteVfsPath}, a
+ *   canonical path, which SQLite passes to the VFS as it is, never as a URI or
+ *   an in-memory database, followed by the name of the VFS.
+ * - A File or EncryptedFile database opens its path on its VFS, an EncryptedFile
+ *   database keyed as the next section describes. Either then prepares a query
+ *   of `sqlite_schema`, because SQLite reads a file only when a statement needs
+ *   it. So the open rolls back a hot journal, and fails for a file that is not
+ *   a database, with SQLITE_NOTADB, or for a hot journal that cannot be rolled
+ *   back.
+ * - The database uses its VFS only through {@link SqliteVfs} or
+ *   {@link SqliteEncryptingVfs}, so any VFS that implements them can hold it,
+ *   and a driver can open each database on the VFS that has it, as
+ *   {@link SqliteVfs.getPaths} tells.
+ * - Flags are READWRITE, CREATE and EXRESCODE, so failures during the open
+ *   already carry extended codes.
+ * - When the open fails, the message is read first and then the handle SQLite
+ *   returned anyway is closed with `sqlite3_close_v2`. Without a handle, as
+ *   when memory runs out, the error is the open's result code.
+ *
+ * ## Encryption
+ *
+ * - The VFS encrypts an EncryptedFile database itself, and a {@link SahPool} does
+ *   it as SQLite3 Multiple Ciphers' `sqlcipher` scheme did with its default
+ *   parameters, those of SQLCipher 4, which `PRAGMA cipher = 'sqlcipher'`
+ *   selected in `@evolu/web` 3 with 2.2.4. The open registers the key for the
+ *   path with {@link SqliteEncryptingVfs.registerKey} before it enters wasm and
+ *   disposes the registration when it returns, by when the VFS has taken the
+ *   key for the database file; the module documentation of `SahPool.ts`
+ *   describes the pool's format. The key never appears in SQL, a URI, an error
+ *   or SQLite's memory, and the caller's key is never modified.
+ * - Then `sqlite3_file_control` with SQLITE_FCNTL_RESERVE_BYTES asks for 80 bytes
+ *   at the end of each page, where the pool keeps the page's IV and HMAC, which
+ *   takes effect for a new database, and `PRAGMA secure_delete = ON` makes
+ *   deletes overwrite freed content, as SQLite3 Multiple Ciphers did for every
+ *   encrypted connection. A {@link SahPool} refuses to turn it off for an
+ *   encrypted database, because a freed page SQLite does not write would fail
+ *   to authenticate, as `SahPool.ts` describes.
+ * - Registering validates nothing, so the read of `sqlite_schema` checks the key.
+ *   A wrong key fails there with SQLITE_NOTADB, from page 1, or with
+ *   SQLITE_CORRUPT when the first page of a hot journal is another page, and
+ *   {@link SqliteError.cause} is the VFS's {@link SqlitePageAuthenticationError}.
+ *   The rollback stops at that first page, which fails to authenticate, so it
+ *   writes no page of the journal and keeps the journal for the right key.
+ *   Before that page, SQLite truncates the database to the size the journal
+ *   records, as the right key's rollback does too. It would extend a shorter
+ *   database by one zeroed page, encrypted with the wrong key, but a commit
+ *   shrinks the file only after it deletes the journal, and a pool refuses a
+ *   VACUUM that would change an encrypted database's page size, so no database
+ *   is shorter than its hot journal records.
+ * - `@evolu/web` with 2.2.4 ran `PRAGMA key = "x'<hex>'"`, SQLCipher's notation
+ *   for a raw key, which SQLite3 Multiple Ciphers 2.2.4 took as a passphrase
+ *   because of a bug
+ *   (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ *   2.2.5), deriving the key with the `sqlcipher` scheme, so those databases
+ *   fail as with a wrong key. {@link createEncryptedSqliteDatabase} then opens
+ *   them with the key {@link deriveLegacySqliteKey} derives through
+ *   {@link SubtleCryptoDep}, and {@link SqliteEncryptedDatabase.keyDerivation}
+ *   says which key opened the database. Nothing rekeys a database.
+ * - `@evolu/web` 1.0.1-preview.6 to 2.4.0 also ran `PRAGMA legacy = 4`, so the
+ *   databases it encrypted fail with SQLITE_NOTADB, as with a wrong key, since
+ *   page 1 is encrypted from byte 16; they have not opened since `@evolu/web`
+ *   3.0.0 (see `SahPool.ts`).
+ * - Only page 1 of the database or a record of its journal that failed to
+ *   authenticate counts as a wrong key. Another page of the database that fails
+ *   means that page 1 proved the key and the page is damaged, so it fails with
+ *   SQLITE_CORRUPT and that page as the cause, also with the key 2.2.4 derived.
+ *   An I/O error fails with its own code, and the VFS's record as its cause,
+ *   and a database whose pages authenticate but whose content is malformed
+ *   fails with SQLite's code and no cause.
+ *
+ * ## Statements
+ *
+ * - SQL is copied into its own memory, which is freed when the call returns,
+ *   because SQLite parses it in place and copies a statement's SQL, which a
+ *   schema change prepares again, only after the parse. Meanwhile a callback,
+ *   such as a collation-needed callback during the parse or a function during a
+ *   step of {@link SqliteDatabase.exec}, can run a query on the same database,
+ *   and that query reuses the scratch memory.
+ * - `sqlite3_prepare_v3` gets the SQL's byte length, counting a NUL terminator,
+ *   which spares SQLite a copy, and, for statements
+ *   {@link SqliteDatabase.prepare} returns, SQLITE_PREPARE_PERSISTENT. Empty SQL
+ *   and SQL with more than one statement are errors, so nothing after the first
+ *   statement is silently ignored. SQLite reads SQL only up to a NUL character,
+ *   and UTF-8 cannot encode a lone surrogate, which encoding would replace with
+ *   U+FFFD, so SQL that contains either fails with
+ *   {@link SqliteInvalidSqlTextError} before SQLite sees it, in
+ *   {@link SqliteDatabase.exec} too.
+ * - A second statement is found by scanning the rest of the SQL as SQLite
+ *   3.53.4's tokenizer reads it, not by preparing it, because SQLite applies
+ *   many pragmas, such as `foreign_keys`, when it prepares them, so SQL that
+ *   fails with {@link SqliteMultipleStatementsError} would still change the
+ *   connection. Only semicolons, whitespace, UTF-8 byte order marks and
+ *   comments may follow the first statement. A pragma in the first statement
+ *   still takes effect when the SQL then fails, as SQLite documents for prepare
+ *   (https://sqlite.org/pragma.html).
+ * - {@link SqliteDatabase.exec} prepares each statement where the previous one
+ *   ended and steps it to completion, so {@link SqliteError.sqlOffset} counts
+ *   from the start of the whole SQL.
+ * - Parameters are positional. Their number is read once at prepare and a run
+ *   with a different number fails, so no binding leaks from a previous run.
+ *   {@link SqliteDatabase.exec} binds none, so a statement with a parameter
+ *   fails there without running, rather than run with NULL.
+ * - Binding: null binds NULL; a 32-bit integer binds with `sqlite3_bind_int`;
+ *   another safe integer with `sqlite3_bind_int64`, so it stays INTEGER; any
+ *   other number with `sqlite3_bind_double`. Text is encoded with `encodeInto`
+ *   and bytes are copied into the scratch memory, both bound with
+ *   SQLITE_TRANSIENT and an explicit byte length, so embedded NUL characters
+ *   survive and an empty value stays non-NULL. A value that can take more than
+ *   64 KiB, counting 3 bytes per UTF-16 code unit of text, is allocated exactly
+ *   and handed over with SQLITE_WASM_DEALLOC instead, so the scratch memory
+ *   does not keep the size of the largest value, and SQLite does not copy it
+ *   twice. Such text is encoded into a new array first, and when JavaScript
+ *   cannot allocate it, the run fails with SQLITE_NOMEM and the operation
+ *   `bind`, while the instance keeps working, because the encoding runs no
+ *   wasm. {@link SqliteDatabase.exec} copies its SQL the same way and fails with
+ *   the operation `exec`. SQLite keeps a bound value until its parameter is
+ *   bound again, so a run that handed a value over clears the bindings before
+ *   it returns, also when it fails, and a prepared statement keeps no large
+ *   value between runs, while smaller ones keep the buffers SQLite reuses for
+ *   them. A {@link SqliteValue} string may contain a lone surrogate, which UTF-8
+ *   cannot encode, so text binds it as U+FFFD, as better-sqlite3 does.
+ * - Reading: `sqlite3_column_type` first. INTEGER and FLOAT read with
+ *   `sqlite3_column_double`, so no BigInt is created; integers beyond 2^53 lose
+ *   precision, as in better-sqlite3. TEXT reads the pointer, then the byte
+ *   length, and decodes keeping a leading byte order mark. A BLOB is one copy
+ *   into its own `ArrayBuffer`, so it can be transferred. With the type read
+ *   first, a NULL pointer is never SQL NULL: for TEXT it is SQLITE_NOMEM, and
+ *   for a BLOB it is an empty value unless `sqlite3_errcode`, read right after,
+ *   returns SQLITE_NOMEM. A NULL column name is SQLITE_NOMEM too, and so is a
+ *   TEXT or BLOB that JavaScript cannot allocate a copy of, whatever error the
+ *   engine throws then, because the copy runs no wasm, so the instance keeps
+ *   working. Each fails the run with the operation `step`. Rows are
+ *   null-prototype objects, so a column named `__proto__` is an ordinary
+ *   property, and of columns with the same name, the last one wins.
+ * - Column names are read after the first row and cached with the statement's
+ *   SQLITE_STMTSTATUS_REPREPARE counter. A schema change re-prepares the
+ *   statement, and `SELECT *` then returns other columns, so the names are read
+ *   again when the counter changed.
+ * - {@link SqliteStatement.run} always resets the statement, so it is reusable
+ *   after an error, and ignores the result: SQLITE_OK after SQLITE_DONE, and a
+ *   failed step's error again after it. A deferred constraint or commit failure
+ *   comes from the last step, so it is not lost. A run whose read fails is cut
+ *   short, and its reset completes the statement, so a write with RETURNING is
+ *   committed although the run fails.
+ * - `changes` compares `sqlite3_total_changes64` before and after the run: 0 when
+ *   it did not move, `sqlite3_changes64` otherwise, as in better-sqlite3, and
+ *   unlike it also 0 when `sqlite3_stmt_readonly` is true, as for a SELECT
+ *   whose function writes. SQLite keeps one count per connection, of the last
+ *   INSERT, UPDATE or DELETE that finished, so reading it alone would report a
+ *   stale count after a SELECT or DDL. {@link SqliteRunResult.changes} says
+ *   which writes the count can come from.
+ * - A callback may run queries on the database, but SQLite forbids resetting or
+ *   finalizing a statement that is stepping and closing a connection while it
+ *   runs. So running or disposing a statement during its own run, and disposing
+ *   the database while one of its operations runs, throw before wasm is
+ *   entered, and the instance keeps working. A callback installed with
+ *   `installWasmFunctions` then fails as a defect.
+ *
+ * ## Exporting and closing
+ *
+ * - {@link SqliteDatabase.export} calls `sqlite3_serialize(db, NULL, &size, 0)`
+ *   for the main schema, copies the pages into their own `ArrayBuffer` and
+ *   frees SQLite's copy. The size has its own memory, because SQLite writes it
+ *   before it finalizes its query, whose trace callback can run a query on the
+ *   same database. `sqlite3_serialize` does not report a failed allocation to
+ *   the connection, so the connection's error is cleared with
+ *   `sqlite3_set_errmsg` first, and NULL then fails with the error the
+ *   connection reports, or else SQLITE_NOMEM, as when JavaScript cannot
+ *   allocate the copy of the pages, which still frees SQLite's copy. SQLite
+ *   gives an empty database its first page before copying, so NULL with a size
+ *   of 0 and no error is only a database that has no pages and cannot get one,
+ *   such as a read-only empty one, which exports as zero bytes. Pages come
+ *   through the pager, so an encrypted database exports as plaintext. SQLite
+ *   zero-fills a page that fails to read and reports success, so the export of
+ *   a File or EncryptedFile database fails when its VFS recorded a failure
+ *   during it, caused by the VFS's record: with SQLITE_CORRUPT for a page that
+ *   failed to authenticate, a {@link SqlitePageAuthenticationError}, and with
+ *   SQLITE_IOERR otherwise.
+ * - Disposing a database finalizes its statements that are still open and then
+ *   calls `sqlite3_close_v2`, so no deferred close keeps the VFS's files open.
+ *
+ * @module
+ */
+import { type EncryptionKey, type Result, type SqliteRow, type SqliteValue, type Task, type Typed, type TypeError } from "@evolu/common";
+import { type SqlitePrimaryResultCode, type SqliteResultCode } from "./Constants.ts";
+import { type SahPool } from "./SahPool.ts";
+import type { SqliteWasmDep } from "./Wasm.ts";
+/**
+ * An open SQLite database. Disposing it while one of its operations runs, as
+ * from a callback, throws.
+ */
+export interface SqliteDatabase extends Disposable {
+    /** Prepares one statement for repeated runs. */
+    readonly prepare: (sql: string) => Result<SqliteStatement, SqlitePrepareError>;
+    /**
+     * Prepares one statement, runs it once as {@link SqliteStatement.run} does and
+     * finalizes it.
+     *
+     * Without SQLITE_PREPARE_PERSISTENT, SQLite prepares it from its lookaside
+     * memory, so a statement that runs once is faster than one from
+     * {@link SqliteDatabase.prepare}: about 20% for a typical query in Node.js
+     * 24.
+     */
+    readonly run: (sql: string, parameters: ReadonlyArray<SqliteValue>) => Result<SqliteRunResult, SqlitePrepareError | SqliteRunError>;
+    /**
+     * Runs SQL that can hold several statements, without parameters, and discards
+     * any rows. Meant for schema changes and pragmas.
+     *
+     * It runs the statements in order and stops at the first that fails. A
+     * statement with a parameter fails with {@link SqliteParameterCountError}
+     * without running, so no parameter silently binds NULL.
+     */
+    readonly exec: (sql: string) => Result<void, SqliteExecError>;
+    /**
+     * Returns the whole database as bytes backed by their own `ArrayBuffer`, so
+     * they can be transferred to another worker.
+     */
+    readonly export: () => Result<Uint8Array<ArrayBuffer>, SqliteError>;
+    /**
+     * Whether no transaction is open.
+     *
+     * After errors such as SQLITE_FULL, SQLITE_IOERR or SQLITE_NOMEM, SQLite may
+     * roll back the transaction itself, and a ROLLBACK then fails. A transaction
+     * helper checks this before rolling back.
+     */
+    readonly isAutocommit: () => boolean;
+}
+/**
+ * A prepared statement. Running or disposing it during its own run, as from a
+ * callback, throws.
+ */
+export interface SqliteStatement extends Disposable {
+    /** The number of SQL parameters, which each run must supply exactly. */
+    readonly parameterCount: number;
+    /**
+     * Binds the parameters, steps to completion, collects the rows and resets the
+     * statement, also when a step fails.
+     */
+    readonly run: (parameters: ReadonlyArray<SqliteValue>) => Result<SqliteRunResult, SqliteRunError>;
+}
+/** The result of {@link SqliteStatement.run}. */
+export interface SqliteRunResult {
+    readonly rows: ReadonlyArray<SqliteRow>;
+    /**
+     * 0 for a read-only statement or a run that changed no rows, and otherwise
+     * SQLite's `sqlite3_changes64`: the rows the connection's last INSERT, UPDATE
+     * or DELETE that finished changed, without those of triggers, foreign key
+     * actions or REPLACE. For an INSERT, UPDATE or DELETE, that is its own count,
+     * unless a write on the same connection finished after it within the run, as
+     * one its profile trace callback runs. For another statement, it is the count
+     * of the last write that finished during the run, as one by a function it
+     * calls or by its trace callback.
+     */
+    readonly changes: number;
+}
+/** An error SQLite reported. */
+export interface SqliteError extends Typed<"SqliteError"> {
+    readonly operation: SqliteOperation;
+    /**
+     * The extended result code, whose primary result code
+     * {@link sqliteResultCodeToPrimary} returns.
+     */
+    readonly extendedCode: SqliteResultCode;
+    /**
+     * From `sqlite3_errmsg`, or from `sqlite3_errstr` of the code when SQLite did
+     * not report the failure to the connection, as for an open without a handle,
+     * an allocation that failed, or an export whose VFS failed to read a page.
+     */
+    readonly message: string;
+    /**
+     * The byte offset in the UTF-8 SQL where SQLite detected the error, from
+     * `sqlite3_error_offset` for a parser error (SQLITE_ERROR from prepare, exec
+     * or step); null for any other error or when the error has no position.
+     */
+    readonly sqlOffset: number | null;
+    /**
+     * The first VFS failure since the top-level operation started, such as the
+     * `QuotaExceededError` behind SQLITE_FULL; null when the VFS reported none.
+     */
+    readonly cause: SqliteVfsFailure | null;
+}
+/** The operation a {@link SqliteError} comes from. */
+export type SqliteOperation = "open" | "prepare" | "bind" | "step" | "exec" | "export";
+/**
+ * Returns the primary result code of a result code, its low 8 bits, such as
+ * SQLITE_CONSTRAINT for SQLITE_CONSTRAINT_NOTNULL. A primary result code
+ * returns itself.
+ */
+export declare const sqliteResultCodeToPrimary: (code: SqliteResultCode) => SqlitePrimaryResultCode;
+/** A failure a VFS method recorded before returning an error code. */
+export interface SqliteVfsFailure {
+    readonly method: SqliteVfsMethod;
+    /**
+     * The path of the file, or null for a method without one or a name that maps
+     * to no path.
+     */
+    readonly path: string | null;
+    /**
+     * What the browser threw, such as a `DOMException`, or what the VFS found
+     * wrong, such as a {@link SqliteShortWriteError}, a
+     * {@link SqlitePageAuthenticationError}, a {@link SahPoolFullError}, a
+     * {@link SahPoolInvalidPathError}, or a
+     * {@link SahPoolEncryptionUnsupportedError}.
+     */
+    readonly error: unknown;
+}
+/** A VFS or I/O method that can record a {@link SqliteVfsFailure}. */
+export type SqliteVfsMethod = "xOpen" | "xDelete" | "xAccess" | "xClose" | "xRead" | "xWrite" | "xTruncate" | "xSync" | "xFileSize" | "xLock" | "xUnlock" | "xCheckReservedLock" | "xFileControl";
+/**
+ * A write that stored fewer or more bytes than requested.
+ *
+ * Firefox reports a full disk with a short count, and Chromium's off-the-record
+ * storage has reported impossible counts; either way the data is not all there,
+ * so the write fails with SQLITE_FULL.
+ */
+export interface SqliteShortWriteError extends Typed<"SqliteShortWrite"> {
+    readonly requested: number;
+    readonly written: number;
+}
+/** Why {@link SqliteDatabase.prepare} failed. */
+export type SqlitePrepareError = SqliteError | SqliteEmptySqlError | SqliteMultipleStatementsError | SqliteInvalidSqlTextError;
+/** The SQL contains no statement, only whitespace or comments. */
+export interface SqliteEmptySqlError extends Typed<"SqliteEmptySqlError"> {
+}
+/** The SQL contains more than one statement. */
+export interface SqliteMultipleStatementsError extends Typed<"SqliteMultipleStatementsError"> {
+}
+/**
+ * The SQL is text SQLite would read as other SQL, so it fails before SQLite
+ * sees it: it contains a NUL character, which SQLite reads SQL only up to, so
+ * it would silently ignore the rest, or a lone surrogate, which UTF-8 cannot
+ * encode, so it would run with U+FFFD in its place.
+ */
+export interface SqliteInvalidSqlTextError extends Typed<"SqliteInvalidSqlText"> {
+}
+/** Why {@link SqliteDatabase.exec} failed. */
+export type SqliteExecError = SqliteError | SqliteInvalidSqlTextError | SqliteParameterCountError;
+/** Why {@link SqliteStatement.run} failed. */
+export type SqliteRunError = SqliteError | SqliteParameterCountError;
+/**
+ * A run supplied a different number of parameters than the SQL has, or
+ * {@link SqliteDatabase.exec}, which supplies none, met a statement with
+ * parameters.
+ */
+export interface SqliteParameterCountError extends Typed<"SqliteParameterCountError"> {
+    readonly expected: number;
+    readonly actual: number;
+}
+/** How to open a database. */
+export type SqliteDatabaseOptions = SqliteMemoryDatabaseOptions | SqliteFileDatabaseOptions | SqliteEncryptedFileDatabaseOptions;
+/**
+ * An in-memory database on the default VFS, which never touches OPFS. Temporary
+ * tables and indexes stay in memory in every mode.
+ */
+export interface SqliteMemoryDatabaseOptions extends Typed<"Memory"> {
+}
+/** An unencrypted database file on a {@link SqliteVfs}, such as a {@link SahPool}. */
+export interface SqliteFileDatabaseOptions extends Typed<"File"> {
+    readonly vfs: SqliteVfs;
+    /**
+     * The canonical path of the file on the VFS, such as `/evolu1.db`, by which
+     * the VFS also lists and deletes it.
+     */
+    readonly path: SqliteVfsPath;
+}
+/**
+ * A database file on a {@link SqliteEncryptingVfs}, which encrypts it, as a
+ * {@link SahPool} does in the format of SQLite3 Multiple Ciphers' `sqlcipher`
+ * scheme.
+ *
+ * Only the database file and its journal are encrypted. `VACUUM INTO` and
+ * `ATTACH` open their file as a database of its own, which is encrypted only
+ * when a key is registered for its path with
+ * {@link SqliteEncryptingVfs.registerKey} while they open it. Otherwise they
+ * write it unencrypted, because SQLite ignores the `KEY` clause of `ATTACH` and
+ * `PRAGMA key`, `rekey` and `cipher`, where 2.2.4 encrypted both with the
+ * database's key, or with the `KEY` of `ATTACH`. A file that `ATTACH` creates
+ * cannot be encrypted, because SQLite reserves no bytes in it, so with a key
+ * registered its first write fails with SQLITE_IOERR_WRITE. `VACUUM INTO` keeps
+ * the reserved bytes, so it can create an encrypted copy, which `ATTACH` then
+ * opens with its key registered.
+ */
+export interface SqliteEncryptedFileDatabaseOptions extends Typed<"EncryptedFile"> {
+    readonly vfs: SqliteEncryptingVfs;
+    /**
+     * The path of the file on the VFS, as {@link SqliteFileDatabaseOptions.path}
+     * describes.
+     */
+    readonly path: SqliteVfsPath;
+    /**
+     * The raw key, which {@link SqliteEncryptingVfs.registerKey} gets while the
+     * file opens.
+     */
+    readonly key: EncryptionKey;
+}
+/** Error returned when a string is not a valid {@link SqliteVfsPath}. */
+export interface SqliteVfsPathError extends TypeError<"SqliteVfsPath"> {
+    readonly value: string;
+}
+/**
+ * The canonical path of a database file on a {@link SqliteVfs}, such as
+ * `/evolu1.db`, one spelling per file, as {@link SqliteVfs.getPaths} lists it.
+ *
+ * A path is canonical when it is its own `new URL(path,
+ * "file://localhost/").pathname`, the path a {@link SahPool} maps a name to, so
+ * the VFS opens, lists and deletes the file by the path the database opened it
+ * with, and an EncryptedFile database registers its key for that file. A
+ * canonical path starts with `/` and is printable ASCII without `?` or `#`, so
+ * SQLite passes it to the VFS as it is, and the paths SQLite derives from it by
+ * appending a suffix, as for the journal, are canonical too. It rejects:
+ *
+ * - Another spelling of a path, such as `evolu1.db`, `/x/../evolu1.db`,
+ *   `FILE:evolu1.db` or `/a b.db` for `/a%20b.db`, and a name with a scheme,
+ *   such as `db:evolu1.db`, which a pool would map to the relative path
+ *   `evolu1.db`.
+ * - A path SQLite reads itself: an empty path and `:memory:`, which open an
+ *   in-memory database, `:localStorage:` and `:sessionStorage:`, which SQLite
+ *   opens on its kvvfs, and a `file:` URI, whose query and fragment SQLite
+ *   strips and whose escapes it decodes, so the VFS would get another name, and
+ *   an EncryptedFile database would be written without its key.
+ * - A path longer than {@link sahPoolMaxDatabasePathSize}, 498 bytes, because a
+ *   pool slot's header holds a path of up to 510 bytes, and SQLite names a
+ *   super-journal by appending 12 bytes to the database's path.
+ */
+export declare const SqliteVfsPath: import("@evolu/common").BrandType<import("@evolu/common").Type<"String", string, string, import("@evolu/common").TypeOfError<"String">, null, import("@evolu/common").TypeOfError<"String">, never, string, true>, "SqliteVfsPath", SqliteVfsPathError>;
+export type SqliteVfsPath = typeof SqliteVfsPath.Output;
+/**
+ * What a database needs from the VFS it opens a file on, and what a driver
+ * needs to tell which databases the VFS has and to delete them. A
+ * {@link SahPool} is one.
+ */
+export interface SqliteVfs {
+    /** The name of the VFS, which a database opens its path with. */
+    readonly vfsName: string;
+    /**
+     * Returns the first failure a method of the VFS recorded since the last
+     * {@link SqliteVfs.clearFailure}, which a {@link SqliteError} carries as its
+     * cause.
+     */
+    readonly getFailure: () => SqliteVfsFailure | null;
+    /**
+     * Forgets the recorded failure; a database calls it before each operation
+     * that does not run inside another operation on the VFS.
+     */
+    readonly clearFailure: () => void;
+    /**
+     * Returns the canonical paths of the files the VFS has, databases and their
+     * journals, such as `/evolu1.db`, so a database opened at a
+     * {@link SqliteVfsPath} is listed by that path. A VFS may derive a file's
+     * canonical path from the name SQLite opened it with, as a {@link SahPool}
+     * lists a file SQLite's opfs-sahpool opened as `evolu1.db` as `/evolu1.db`.
+     */
+    readonly getPaths: () => ReadonlyArray<string>;
+    /**
+     * Deletes the file with a canonical path, as {@link SqliteVfs.getPaths}
+     * returns it, and the files SQLite keeps beside it, such as its `-journal`.
+     * The file goes first, so a failure never leaves a database without the
+     * journal that would roll it back. Returns false when the VFS has no file
+     * with the path, as for a path that is not canonical, and throws when a
+     * connection has one of the files open.
+     */
+    readonly unlink: (path: string) => Result<boolean, SqliteVfsIoError>;
+}
+/**
+ * A {@link SqliteVfs} that encrypts a database file whose path has a key
+ * registered while the file opens, as an EncryptedFile database needs.
+ *
+ * The database asks SQLite to leave the last 80 bytes of each page of a new
+ * database unused, so the VFS can store data of its own there, as a
+ * {@link SahPool} stores the page's IV and HMAC.
+ *
+ * A read of a page that fails to authenticate fails with SQLITE_NOTADB for page
+ * 1 and SQLITE_CORRUPT for any other page, and records a
+ * {@link SqlitePageAuthenticationError}, by which the database tells it from
+ * other failures, so an export that reads the page fails with SQLITE_CORRUPT
+ * rather than SQLITE_IOERR.
+ */
+export interface SqliteEncryptingVfs extends SqliteVfs {
+    /**
+     * Registers a raw key for a path until the registration is disposed, as an
+     * EncryptedFile database does while it opens. The path is the one spelling by
+     * which the VFS opens the file, so it is registered as it is. When the VFS
+     * opens the path as a main database, it copies the key and encrypts that file
+     * and its journal with it until the file closes, also for the file of an
+     * `ATTACH` or `VACUUM INTO` that opens it meanwhile. The caller's key is
+     * never modified.
+     */
+    readonly registerKey: (path: SqliteVfsPath, key: EncryptionKey) => Disposable;
+}
+/**
+ * The storage of a VFS failed outside SQLite, as when {@link SqliteVfs.unlink}
+ * deletes a file.
+ */
+export interface SqliteVfsIoError extends Typed<"SqliteVfsIoError"> {
+    /**
+     * What the storage threw, such as a `DOMException`, or a
+     * {@link SqliteShortWriteError} for a write that stored a different number of
+     * bytes.
+     */
+    readonly cause: unknown;
+}
+/**
+ * A page of an encrypted file that failed to authenticate, because the key is
+ * wrong or the page was altered or cut short, as a {@link SqliteEncryptingVfs}
+ * records it.
+ */
+export interface SqlitePageAuthenticationError extends Typed<"SqlitePageAuthenticationError"> {
+    /**
+     * The number of the database page, counting from 1, also for a page in a
+     * journal.
+     */
+    readonly pageNumber: number;
+}
+/**
+ * Opens a database.
+ *
+ * With a wrong key or a file that is not a database, it fails with
+ * SQLITE_NOTADB, or with SQLITE_CORRUPT for a wrong key and a hot journal whose
+ * first record is not page 1. On a {@link SahPool}, an encrypted database opened
+ * without its key while it has a hot journal that records pages fails with
+ * SQLITE_CANTOPEN, and the journal stays for the key. A leftover journal that
+ * is not hot, such as one `journal_mode = PERSIST` or TRUNCATE keeps, gives
+ * SQLITE_NOTADB, as no journal does. For encrypted databases that 2.2.4 may
+ * have keyed, use {@link createEncryptedSqliteDatabase}.
+ */
+export declare const createSqliteDatabase: (deps: SqliteWasmDep) => (options: SqliteDatabaseOptions) => Result<SqliteDatabase, SqliteError>;
+/**
+ * Options for {@link createEncryptedSqliteDatabase}: an EncryptedFile database
+ * on a {@link SahPool}, because 2.2.4 wrote only pool files, and the fallback to
+ * its key reads the salt with {@link SahPool.read}.
+ */
+export interface SqliteEncryptedDatabaseOptions extends SqliteEncryptedFileDatabaseOptions {
+    readonly vfs: SahPool;
+}
+/**
+ * Opens an EncryptedFile database on a pool, falling back to the key
+ * `@evolu/sqlite-wasm` 2.2.4 derived.
+ *
+ * `@evolu/web` passed 2.2.4 the key as the SQL text `x'<hex>'`, SQLCipher's
+ * notation for a raw key, which SQLite3 Multiple Ciphers 2.2.4 treated as a
+ * passphrase because of a bug
+ * (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ * 2.2.5). So every database it encrypted is keyed with PBKDF2-HMAC-SHA512 of
+ * that text, not with the key itself. This Task:
+ *
+ * 1. Opens with the raw key. A new or empty file always accepts it.
+ * 2. Only when a wrong key failed it, so page 1 of the database or a record of its
+ *    hot journal failed to authenticate, which the pool records as a
+ *    {@link SqlitePageAuthenticationError}, reads the first 16 bytes of the file
+ *    through {@link SahPool.read}: the unencrypted cipher salt. Another page of
+ *    the database that fails to authenticate is damaged, because page 1 proved
+ *    the key, so the open fails with SQLITE_CORRUPT.
+ * 3. Derives the legacy key with {@link deriveLegacySqliteKey}, opens again with it
+ *    as the raw key, and zeroes it.
+ *
+ * The result says which key opened the database. When neither key opens it, the
+ * error is the raw key's, unless the second open failed otherwise. Rekeying a
+ * legacy database to the raw key is a separate decision: it rewrites every
+ * page, needs space, and makes the database unreadable to 2.2.4 tabs that share
+ * the pool.
+ */
+export declare const createEncryptedSqliteDatabase: (options: SqliteEncryptedDatabaseOptions) => Task<SqliteEncryptedDatabase, SqliteError | SqliteVfsIoError, SqliteWasmDep & SubtleCryptoDep>;
+/** The result of {@link createEncryptedSqliteDatabase}. */
+export interface SqliteEncryptedDatabase {
+    readonly database: SqliteDatabase;
+    readonly keyDerivation: SqliteKeyDerivation;
+}
+/**
+ * Which key opened an encrypted database: the raw key, or the key 2.2.4 derived
+ * from it because of a bug in SQLite3 Multiple Ciphers, which
+ * {@link deriveLegacySqliteKey} describes.
+ */
+export type SqliteKeyDerivation = "Raw" | "Legacy224";
+/**
+ * Derives the key `@evolu/sqlite-wasm` 2.2.4 used: PBKDF2-HMAC-SHA512 with
+ * 256000 iterations and a 32-byte output, over the UTF-8 text `x'` followed by
+ * the key in lowercase hex and `'`, salted with the database's first 16 bytes.
+ *
+ * It exists because of a bug in SQLite3 Multiple Ciphers 2.2.4, which 2.2.4
+ * packaged. `x'<hex>'` is SQLCipher's notation for a raw key, which
+ * `@evolu/web` used, but that version took it as a passphrase and derived the
+ * key from the text
+ * (https://github.com/utelle/SQLite3MultipleCiphers/issues/218, fixed in
+ * 2.2.5). So the databases it encrypted are keyed with this derivation, and
+ * opening them needs it for as long as they exist, because nothing rekeys
+ * them.
+ *
+ * The text is built byte by byte, so no string holds the key, and zeroed once
+ * WebCrypto has imported it.
+ */
+export declare const deriveLegacySqliteKey: (key: EncryptionKey, salt: Uint8Array) => Task<EncryptionKey, never, SubtleCryptoDep>;
+/** WebCrypto, which derives legacy keys. */
+export interface SubtleCryptoDep {
+    readonly subtleCrypto: SubtleCrypto;
+}
+//# sourceMappingURL=Database.d.ts.map

package/dist/src/Database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../src/Database.ts"],"names":[],"mappings":"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"}