@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/providers/sqliteBackup.js

@@ -0,0 +1,365 @@
+/**
+ * Encrypted, consistent copies of SQLite databases, and the staged restore
+ * that puts them back (#1723). Ported from yourPHR (`sqlite-backup.ts`,
+ * yourphr#461, #602, #608, #787, #866, #914), with these changes:
+ *
+ * - __One encrypted file per database__, not one file holding every
+ *   database's tables. A restore needs no table-name split, and two databases
+ *   may hold tables of the same name.
+ * - __Every database's snapshot is taken before any copying starts.__ Each
+ *   source gets its own connection with its backup file attached; a read
+ *   transaction is opened on every one of them, back to back, and only then
+ *   are they copied. SQLite allows ten attached databases per connection, so
+ *   one connection for all of them would cap a site at five databases; this
+ *   has no cap. The live files are in WAL mode, so these readers never block
+ *   the site's writers, and a write committed after the snapshot is in none of
+ *   the copies.
+ * - `sqlite_sequence` (AUTOINCREMENT counters) and `user_version` are copied,
+ *   so a restored table never hands out an id it handed out before.
+ * - Staging writes `<live>.staged` beside each live file, the path applying
+ *   reads (yourphr#866: they were different directories), and is all or
+ *   nothing: on any failure every staged file is removed.
+ * - Applying moves the live file's `-wal` and `-shm` aside with it
+ *   (yourphr#866), so a leftover WAL can never replay onto the restored file.
+ *
+ * Every function here is synchronous SQLite and can take minutes on a large
+ * database: the managers call them through `runOffThread`, never on the thread
+ * that answers requests (yourphr#787, #914). Keys travel in `workerData`
+ * (memory), never argv or the environment.
+ */
+import { chmodSync, copyFileSync, existsSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { Worker } from 'node:worker_threads';
+/** The staged file for a live database: beside it, so staging and applying name the same path. */
+export const stagedPath = (live) => `${live}.staged`;
+/** SQLCipher key pragma escaping, as SqliteDatabaseProvider does it. */
+function quoteKey(key) {
+    return `'${key.replace(/'/g, "''")}'`;
+}
+/** Open a file the way SqliteDatabaseProvider does: SQLCipher, keyed when a key is given. */
+function openKeyed(Database, file, key) {
+    // Checked here, not with `fileMustExist`: SQLite opens an ATTACHed file with
+    // the main file's flags, and without CREATE the backup or staged file could
+    // not be made.
+    if (!existsSync(file))
+        throw new Error(`${file} does not exist`);
+    const db = new Database(file);
+    try {
+        db.pragma("cipher='sqlcipher'");
+        if (key)
+            db.pragma(`key=${quoteKey(key)}`);
+        // The first read: a wrong key fails here.
+        db.prepare('SELECT COUNT(*) AS n FROM sqlite_master').get();
+        return db;
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+}
+/**
+ * Copies every table (with its rows), index, trigger and view from one schema
+ * of the connection into another, inside the caller's transaction. This is
+ * sqlcipher_export(), spelled out: SQLite3MultipleCiphers does not ship it.
+ * Tables are created and filled before any index or trigger exists, so the
+ * copy fires no trigger.
+ */
+function copyObjects(db, from, to) {
+    const all = db
+        .prepare(`SELECT type, name, sql FROM ${from}.sqlite_master WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY CASE type WHEN 'table' THEN 0 WHEN 'index' THEN 1 WHEN 'trigger' THEN 2 ELSE 3 END`)
+        .all();
+    // A virtual table (FTS5) owns shadow tables, <table>_data, _idx, _content,
+    // _docsize, _config: recreating it recreates them, and creating them by hand
+    // is refused. Their rows come back through the INSERT into the virtual table.
+    const virtual = all.filter((o) => /^CREATE VIRTUAL TABLE/i.test(o.sql)).map((o) => o.name);
+    const shadow = (name) => virtual.some((v) => name.startsWith(`${v}_`));
+    let tables = 0;
+    for (const object of all) {
+        if (shadow(object.name))
+            continue;
+        // CREATE TABLE x -> CREATE TABLE to.x: the one rewrite sqlcipher_export
+        // makes. sqlite_master SQL never carries a schema prefix.
+        const ddl = object.sql.replace(/^(CREATE (?:TABLE|INDEX|UNIQUE INDEX|TRIGGER|VIEW|VIRTUAL TABLE))\s+(?:IF NOT EXISTS\s+)?("[^"]+"|\[[^\]]+\]|`[^`]+`|\S+)/i, (_m, head, name) => `${head} ${to}.${name}`);
+        db.exec(ddl);
+        if (object.type !== 'table')
+            continue;
+        tables++;
+        const quoted = `"${object.name.replace(/"/g, '""')}"`;
+        if (virtual.includes(object.name)) {
+            // A virtual table's rowids are carried explicitly: SELECT * leaves them
+            // out, and the copy would be renumbered.
+            const cols = db.prepare(`SELECT name FROM ${from}.pragma_table_info(?)`).all(object.name)
+                .map((c) => `"${c.name.replace(/"/g, '""')}"`).join(', ');
+            db.exec(`INSERT INTO ${to}.${quoted} (rowid, ${cols}) SELECT rowid, ${cols} FROM ${from}.${quoted}`);
+        }
+        else {
+            db.exec(`INSERT INTO ${to}.${quoted} SELECT * FROM ${from}.${quoted}`);
+        }
+    }
+    // AUTOINCREMENT counters: without them a restored table could hand out an
+    // id it had already used for a deleted row.
+    const hasSequence = db.prepare(`SELECT 1 FROM ${from}.sqlite_master WHERE name = 'sqlite_sequence'`).get();
+    if (hasSequence && db.prepare(`SELECT 1 FROM ${to}.sqlite_master WHERE name = 'sqlite_sequence'`).get()) {
+        db.exec(`DELETE FROM ${to}.sqlite_sequence`);
+        db.exec(`INSERT INTO ${to}.sqlite_sequence (name, seq) SELECT name, seq FROM ${from}.sqlite_sequence`);
+    }
+    const userVersion = db.pragma(`${from}.user_version`, { simple: true });
+    if (userVersion)
+        db.pragma(`${to}.user_version = ${Number(userVersion)}`);
+    return tables;
+}
+/** SQLite's full integrity check of an open database; throws naming what it found. */
+function requireIntegrity(db, what) {
+    const result = String(db.pragma('integrity_check')[0]?.integrity_check ?? 'no result');
+    if (result !== 'ok')
+        throw new Error(`${what} failed its integrity check: ${result}`);
+}
+/**
+ * Write an encrypted copy of each database under `backupKey`. A database that
+ * cannot be opened or copied is named in `failed`, its partial file removed;
+ * the others are still written. A target that already exists is never
+ * overwritten.
+ */
+export function exportDatabasesSync(Database, exports, backupKey) {
+    if (!backupKey.trim()) {
+        throw new Error('a backup key is required: database backups are always encrypted');
+    }
+    const outcome = { written: [], failed: [] };
+    const open = [];
+    const fail = (job, err, db) => {
+        try {
+            db?.close();
+        }
+        catch { /* already failing */ }
+        rmSync(job.target, { force: true });
+        outcome.failed.push({ name: job.name, error: err.message });
+    };
+    // 1. A connection per database, its backup file attached under the backup key.
+    for (const job of exports) {
+        if (existsSync(job.target)) {
+            outcome.failed.push({ name: job.name, error: `${path.basename(job.target)} already exists; a backup never overwrites one` });
+            continue;
+        }
+        let db;
+        try {
+            db = openKeyed(Database, job.source, job.sourceKey);
+            db.prepare(`ATTACH DATABASE ? AS backup KEY ${quoteKey(backupKey)}`).run(job.target);
+            open.push({ job, db });
+        }
+        catch (err) {
+            fail(job, err, db);
+        }
+    }
+    // 2. Every snapshot, back to back, before any copying: one point in time.
+    const reading = [];
+    for (const entry of open) {
+        try {
+            entry.db.exec('BEGIN');
+            entry.db.prepare('SELECT COUNT(*) AS n FROM main.sqlite_master').get();
+            reading.push(entry);
+        }
+        catch (err) {
+            fail(entry.job, err, entry.db);
+        }
+    }
+    // 3. Copy each, then close and prove the copy opens under the backup key.
+    for (const { job, db } of reading) {
+        try {
+            const tables = copyObjects(db, 'main', 'backup');
+            db.exec('COMMIT');
+            db.close();
+            const check = openKeyed(Database, job.target, backupKey);
+            try {
+                requireIntegrity(check, `the backup of ${job.name}`);
+            }
+            finally {
+                check.close();
+            }
+            chmodSync(job.target, 0o600);
+            outcome.written.push({ name: job.name, target: job.target, sizeBytes: statSync(job.target).size, tables });
+        }
+        catch (err) {
+            try {
+                if (db.inTransaction)
+                    db.exec('ROLLBACK');
+            }
+            catch { /* closing anyway */ }
+            fail(job, err, db.open ? db : undefined);
+        }
+    }
+    return outcome;
+}
+/**
+ * Stage a restore: each backup file is opened under the backup key,
+ * integrity-checked, and copied into `<live>.staged` under the target
+ * database's key, which is then opened and checked too. All or nothing: if
+ * any database fails, every staged file is removed and the error names it.
+ * Live files are never touched.
+ */
+export function stageDatabasesSync(Database, stages, backupKey) {
+    if (!backupKey.trim()) {
+        throw new Error('a backup key is required to read a database backup');
+    }
+    const outcome = { staged: [] };
+    try {
+        for (const stage of stages) {
+            const staged = stagedPath(stage.live);
+            rmSync(staged, { force: true });
+            let db;
+            try {
+                db = openKeyed(Database, stage.backupFile, backupKey);
+            }
+            catch (err) {
+                throw new Error(`the backup of ${stage.name} cannot be read — wrong backup key, or not a backup: ${err.message}`, { cause: err });
+            }
+            let tables;
+            try {
+                requireIntegrity(db, `the backup of ${stage.name}`);
+                db.prepare(`ATTACH DATABASE ? AS staged KEY ${quoteKey(stage.targetKey)}`).run(staged);
+                db.exec('BEGIN');
+                try {
+                    tables = copyObjects(db, 'main', 'staged');
+                    db.exec('COMMIT');
+                }
+                catch (err) {
+                    db.exec('ROLLBACK');
+                    throw err;
+                }
+            }
+            finally {
+                db.close();
+            }
+            const check = openKeyed(Database, staged, stage.targetKey);
+            try {
+                requireIntegrity(check, `the staged copy of ${stage.name}`);
+            }
+            finally {
+                check.close();
+            }
+            chmodSync(staged, 0o600);
+            outcome.staged.push({ name: stage.name, staged, live: stage.live, tables });
+        }
+        return outcome;
+    }
+    catch (err) {
+        for (const stage of stages)
+            rmSync(stagedPath(stage.live), { force: true });
+        throw err;
+    }
+}
+export function runOffThread(job, timeoutMs) {
+    // Compiled, the worker is the .js beside this file. From source (vitest,
+    // tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './sqliteBackupWorker.ts' : './sqliteBackupWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const driver = createRequire(import.meta.url).resolve('better-sqlite3-multiple-ciphers');
+        const workerData = { ...job, driver };
+        const worker = new Worker(entry, { workerData, ...(fromSource ? { execArgv: ['--import', 'tsx'] } : {}) });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`the database ${job.kind === 'export' ? 'backup' : 'restore'} did not finish within ${timeoutMs} ms (ngdpbase.database.backup.worker-timeout-ms) and was stopped`)));
+            void worker.terminate();
+        }, timeoutMs);
+        worker.once('message', (m) => {
+            settle(() => (m.ok ? resolve(m.result) : reject(new Error(m.error))));
+        });
+        worker.once('error', (err) => settle(() => reject(err)));
+        worker.once('exit', (code) => settle(() => reject(new Error(`the database backup worker exited (code ${code}) without a result`))));
+    });
+}
+/** Where the manifest of a staged restore lives: beside the application database. */
+export const manifestPath = (applicationFile) => `${applicationFile}.restore.json`;
+export function writeManifest(file, manifest) {
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/**
+ * Apply a staged restore at start, before any database opens. Each live file,
+ * with its `-wal` and `-shm`, steps aside as `*.pre-restore` (`-wal`/`-shm`
+ * beside it, so the kept copy still opens as it was), and the staged file
+ * takes its name. A rename, never a write into a live database.
+ *
+ * All or nothing: if any database the manifest names is not staged, nothing
+ * is applied; what is staged is renamed `*.incomplete`, so it is neither
+ * applied nor retried. A staged file with no manifest (staging was
+ * interrupted) is set aside the same way. `allowed` says which live paths may
+ * be replaced, so a tampered manifest cannot rename an arbitrary file.
+ */
+export function applyStagedRestore(applicationFile, allowed) {
+    const manifestFile = manifestPath(applicationFile);
+    const dir = path.dirname(applicationFile);
+    const stray = () => (existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.db.staged')).map((f) => path.join(dir, f)) : []);
+    if (!existsSync(manifestFile)) {
+        const leftovers = stray();
+        if (leftovers.length === 0)
+            return null;
+        for (const f of leftovers)
+            move(f, `${f}.incomplete`);
+        return { applied: [], refused: `staged database files with no restore manifest (an interrupted staging): ${leftovers.map((f) => path.basename(f)).join(', ')} — set aside as *.incomplete` };
+    }
+    const setAside = (reason) => {
+        for (const f of stray())
+            move(f, `${f}.incomplete`);
+        move(manifestFile, `${manifestFile}.incomplete`);
+        return { applied: [], refused: reason };
+    };
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
+    }
+    catch (err) {
+        return setAside(`the restore manifest cannot be read: ${err.message}`);
+    }
+    const entries = Array.isArray(manifest?.databases) ? manifest.databases : [];
+    const bad = entries.find((e) => !allowed(e.live) || e.staged !== stagedPath(e.live));
+    if (entries.length === 0 || bad) {
+        return setAside(bad ? `the restore manifest names ${bad.live}, which is not a database of this site` : 'the restore manifest names no database');
+    }
+    const missing = entries.filter((e) => !existsSync(e.staged));
+    if (missing.length > 0) {
+        return setAside(`only ${entries.length - missing.length} of ${entries.length} databases were staged (missing: ${missing.map((e) => e.name).join(', ')}), and they belong together`);
+    }
+    const applied = [];
+    for (const entry of entries) {
+        const kept = `${entry.live}.pre-restore`;
+        // A previous restore's kept WAL must not pair with this restore's kept file.
+        for (const sibling of [`${kept}-wal`, `${kept}-shm`])
+            rmSync(sibling, { force: true });
+        if (existsSync(entry.live)) {
+            move(entry.live, kept);
+            for (const suffix of ['-wal', '-shm']) {
+                if (existsSync(`${entry.live}${suffix}`))
+                    move(`${entry.live}${suffix}`, `${kept}${suffix}`);
+            }
+        }
+        // Never a WAL beside the restored file that is not its own.
+        for (const suffix of ['-wal', '-shm'])
+            rmSync(`${entry.live}${suffix}`, { force: true });
+        move(entry.staged, entry.live);
+        applied.push({ name: entry.name, live: entry.live, kept });
+    }
+    unlinkSync(manifestFile);
+    return { applied };
+}
+/** A rename; a copy and unlink when the two paths are on different devices. */
+function move(from, to) {
+    try {
+        renameSync(from, to);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        copyFileSync(from, to);
+        unlinkSync(from);
+    }
+}

package/lib/src/providers/sqliteLocation.d.ts

@@ -0,0 +1,17 @@
+/** Linux statfs f_type values for network filesystems (linux/magic.h). */
+export declare const NETWORK_FILESYSTEMS: Readonly<Record<number, string>>;
+export interface StatFsLike {
+    type: number;
+}
+/** The network filesystem `target` would live on, or null (#1714: shared by the SQLite and file stores). */
+export declare function networkFilesystemAt(target: string, statfs?: (path: string) => StatFsLike, platform?: string): {
+    name: string;
+    probe: string;
+    type: number;
+} | null;
+/**
+ * Throws, naming the path and the filesystem, when `databaseFile` would be opened on a network
+ * filesystem. A file that does not exist yet is judged by the nearest directory that does, since
+ * that is where SQLite will create it.
+ */
+export declare function refuseNetworkFilesystem(databaseFile: string, statfs?: (path: string) => StatFsLike, platform?: string): void;

package/lib/src/providers/sqliteLocation.js

@@ -0,0 +1,55 @@
+/**
+ * SQLite must not live on a network filesystem (ported from yourPHR, yourphr#628; ngdpbase #1536).
+ *
+ * Every database here runs in WAL mode, and WAL coordinates readers and writers through a `-shm`
+ * file each connection mmaps shared-writable. That does not work over NFS or SMB, and SQLite
+ * documents WAL there as unsupported: the database will not open, or opens and corrupts — on PHI,
+ * discovered at restore time. So the boot stats where each database will ACTUALLY live, whatever root
+ * it was composed from or however it was labelled, and refuses when that is a known network
+ * filesystem.
+ *
+ * Deliberately narrow, as the issue decided:
+ *   - fail-CLOSED on a known-bad type, fail-OPEN on anything unrecognised — the magic numbers are
+ *     Linux's; a laptop's APFS (0x1a on macOS) must boot, not be refused;
+ *   - boot-time only: a path that becomes a mount later is not re-checked;
+ *   - SQLite files only. The backup destination SHOULD be on a NAS, and is never checked here.
+ */
+import { existsSync, statfsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** Linux statfs f_type values for network filesystems (linux/magic.h). */
+export const NETWORK_FILESYSTEMS = {
+    0x6969: 'NFS',
+    0x517b: 'SMB',
+    0xff534d42: 'CIFS',
+    0xfe534d42: 'SMB2'
+};
+/** The network filesystem `target` would live on, or null (#1714: shared by the SQLite and file stores). */
+export function networkFilesystemAt(target, statfs = (p) => statfsSync(p), platform = process.platform) {
+    if (platform !== 'linux')
+        return null; // the numbers below are Linux's; elsewhere, unknown = allowed
+    let probe = resolve(target);
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    let type;
+    try {
+        type = statfs(probe).type;
+    }
+    catch {
+        return null; // cannot tell: fail open, as for an unrecognised type
+    }
+    const name = NETWORK_FILESYSTEMS[type];
+    return name ? { name, probe, type } : null;
+}
+/**
+ * Throws, naming the path and the filesystem, when `databaseFile` would be opened on a network
+ * filesystem. A file that does not exist yet is judged by the nearest directory that does, since
+ * that is where SQLite will create it.
+ */
+export function refuseNetworkFilesystem(databaseFile, statfs = (p) => statfsSync(p), platform = process.platform) {
+    const found = networkFilesystemAt(databaseFile, statfs, platform);
+    if (found) {
+        throw new Error(`refusing to start: the SQLite database ${databaseFile} would live on ${found.name} (${found.probe}, filesystem type 0x${found.type.toString(16)}). ` +
+            'SQLite in WAL mode needs shared memory, which network filesystems do not provide — the database would fail to open or corrupt. ' +
+            'Put the data directory (FAST_STORAGE) on local disk; backups may still go to the NAS (#1536).');
+    }
+}

package/lib/src/providers/sqliteMigrations.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Schema migrations — dated, run-once, recorded, transactional. Ported from yourPHR (yourphr#542),
+ * where it runs in production; ngdpbase #1536. A migration is a FROZEN SNAPSHOT of intent at its
+ * date — it never references live code, because the live code moves on and the migration must keep
+ * describing what it did the day it ran.
+ *
+ * Two rules yourPHR paid to learn, made structural here:
+ *
+ *   - yourphr#528: ADD COLUMN leaves every EXISTING row NULL, not zero — and NULL + 1 is NULL, so
+ *     a revocation counter "incremented" for months without moving, reporting success throughout.
+ *     addColumnWithDefault() is the required spelling for counter-like columns: default for new
+ *     rows, explicit backfill for existing ones, in the same migration.
+ *   - Downgrade protection: a database that records a migration THIS build has never heard of is a
+ *     database from the future, and opening it "best effort" is how schema corruption happens.
+ *     Refuse to start instead.
+ *
+ * No down() — deliberately: the rollback story is a backup taken before anything migrates, not a
+ * reverse script that was never tested against real data.
+ */
+import type Database from 'better-sqlite3-multiple-ciphers';
+export interface Migration {
+    /** Dated, sortable: YYYYMMDDHHMMSS. The registry must be strictly ascending. */
+    id: string;
+    description: string;
+    up: (db: InstanceType<typeof Database>) => void;
+}
+export interface MigrationReport {
+    applied: string[];
+    skipped: number;
+}
+/**
+ * ADD COLUMN with a default AND a backfill of existing rows, in one statement pair — the yourphr#528
+ * spelling. SQLite's ADD COLUMN ... DEFAULT only applies the default to rows created afterwards
+ * on some historic versions and to reads via the schema on others; the explicit UPDATE removes
+ * the ambiguity for every row that already exists.
+ */
+export declare function addColumnWithDefault(db: InstanceType<typeof Database>, table: string, column: string, type: 'INTEGER' | 'TEXT' | 'REAL', defaultValue: number | string): void;
+/**
+ * Applies every pending migration, in order, each in its own transaction. Stops loudly at the
+ * first failure, leaving everything before it applied and everything from it untouched — a rerun
+ * after the fix picks up exactly there.
+ */
+/**
+ * `ledgerTable` names the table the applied ids are recorded in. A second database keeps its own
+ * name (yourphr#784): a backup holding several databases' tables in one file splits them back BY
+ * TABLE NAME on restore, and two tables called schema_migrations could not be told apart.
+ */
+export declare function runMigrations(db: InstanceType<typeof Database>, registry: Migration[], ledgerTable?: string): MigrationReport;

package/lib/src/providers/sqliteMigrations.js

@@ -0,0 +1,72 @@
+const ID_SHAPE = /^\d{14}$/;
+/**
+ * ADD COLUMN with a default AND a backfill of existing rows, in one statement pair — the yourphr#528
+ * spelling. SQLite's ADD COLUMN ... DEFAULT only applies the default to rows created afterwards
+ * on some historic versions and to reads via the schema on others; the explicit UPDATE removes
+ * the ambiguity for every row that already exists.
+ */
+export function addColumnWithDefault(db, table, column, type, defaultValue) {
+    const quoted = typeof defaultValue === 'string' ? `'${defaultValue.replace(/'/g, "''")}'` : String(defaultValue);
+    db.exec(`ALTER TABLE "${table}" ADD COLUMN "${column}" ${type} NOT NULL DEFAULT ${quoted}`);
+    db.exec(`UPDATE "${table}" SET "${column}" = ${quoted} WHERE "${column}" IS NULL`);
+}
+/**
+ * Applies every pending migration, in order, each in its own transaction. Stops loudly at the
+ * first failure, leaving everything before it applied and everything from it untouched — a rerun
+ * after the fix picks up exactly there.
+ */
+/**
+ * `ledgerTable` names the table the applied ids are recorded in. A second database keeps its own
+ * name (yourphr#784): a backup holding several databases' tables in one file splits them back BY
+ * TABLE NAME on restore, and two tables called schema_migrations could not be told apart.
+ */
+export function runMigrations(db, registry, ledgerTable = 'schema_migrations') {
+    // Digits are allowed after the first letter: an add-on slug may carry them ('calendar2'), and its
+    // ledger is named after the slug (ngdp-accounting-addons#13).
+    if (!/^[a-z][a-z0-9_]*$/.test(ledgerTable))
+        throw new Error(`migration ledger table ${ledgerTable} is not a plain name`);
+    // Registry hygiene before anything touches the database.
+    let previous = '';
+    for (const m of registry) {
+        if (!ID_SHAPE.test(m.id)) {
+            throw new Error(`migration id ${m.id} is not YYYYMMDDHHMMSS`);
+        }
+        if (m.id <= previous) {
+            throw new Error(`migration ids must be strictly ascending: ${m.id} follows ${previous}`);
+        }
+        previous = m.id;
+    }
+    db.exec(`CREATE TABLE IF NOT EXISTS ${ledgerTable} (
+    id TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    applied_at TEXT NOT NULL
+  )`);
+    // Downgrade protection: an applied id the registry does not know means the database belongs to a
+    // NEWER build. Opening it anyway is how corruption happens — refuse, name the ids.
+    const appliedIds = new Set(db.prepare(`SELECT id FROM ${ledgerTable}`).all().map((r) => r.id));
+    const known = new Set(registry.map((m) => m.id));
+    const fromTheFuture = [...appliedIds].filter((id) => !known.has(id));
+    if (fromTheFuture.length > 0) {
+        throw new Error(`database schema is newer than this build — applied migrations this build does not know: ${fromTheFuture.sort().join(', ')}. Refusing to start; upgrade the app or restore the matching backup.`);
+    }
+    const report = { applied: [], skipped: 0 };
+    for (const migration of registry) {
+        if (appliedIds.has(migration.id)) {
+            report.skipped++;
+            continue;
+        }
+        db.exec('BEGIN');
+        try {
+            migration.up(db);
+            db.prepare(`INSERT INTO ${ledgerTable} (id, description, applied_at) VALUES (?, ?, ?)`).run(migration.id, migration.description, new Date().toISOString());
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            // The id in the error is what makes a 2am failure debuggable from the log line alone.
+            throw new Error(`migration ${migration.id} (${migration.description}) failed and was rolled back: ${err.message}`, { cause: err });
+        }
+        report.applied.push(migration.id);
+    }
+    return report;
+}

package/lib/src/rendering/githubAlerts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GitHub alerts (#1493): a blockquote whose first line is exactly `[!NOTE]`,
+ * `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` renders in GitHub's
+ * own shape, stored as written:
+ *
+ *   <div class="markdown-alert markdown-alert-note">
+ *     <p class="markdown-alert-title"><svg …/>Note</p>
+ *     …the rest of the quote…
+ *   </div>
+ *
+ * Written here rather than taken from `markdown-it-github-alerts`: that plugin
+ * reads any text after the marker as a custom title and writes it into the
+ * page unescaped, which would let `> [!NOTE] <img onerror=…>` past the HTML
+ * policy (#1623). GitHub itself does not make an alert of a marker with text
+ * after it on the same line, and neither does this rule. Titles are fixed.
+ *
+ * Icons: GitHub's Octicons (info, light-bulb, report, alert, stop), MIT
+ * licensed, https://github.com/primer/octicons.
+ */
+import type MarkdownIt from 'markdown-it';
+/** Turn qualifying blockquotes into GitHub alerts. */
+export declare function githubAlerts(md: MarkdownIt): void;

package/lib/src/rendering/htmlPolicy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The one HTML policy for page content (#1623).
+ *
+ * Raw HTML an author writes in a page is held to one allow-list, declared once
+ * in configuration (`ngdpbase.markup.html-policy`) and enforced here by one
+ * parser — sanitize-html, built on htmlparser2. Save and render ask the same
+ * question of the same code:
+ *
+ *   - render: {@link filterAuthorHtml} rewrites each piece of author HTML,
+ *     keeping what the policy allows and dropping the rest. It runs inside
+ *     markdown-it's `html_block` / `html_inline` renderers
+ *     (src/rendering/markdownConverter.ts), so it sees author HTML and nothing
+ *     else: plugin, link and variable output is merged in after markdown-it,
+ *     from placeholders, and is never seen by it.
+ *   - save: {@link htmlPolicyViolations} names what that rewrite would drop,
+ *     and SecurityFilter refuses the save with those names.
+ *
+ * Why per tag, not per fragment: markdown-it hands author HTML over in pieces —
+ * `<div>` and `</div>` arrive as separate tokens around the markdown between
+ * them, and inline HTML arrives one tag per token. A tree sanitiser given a
+ * piece balances it (`<div>` becomes `<div></div>`) and drops a close it never
+ * saw opened, which would break every page that wraps markdown in HTML. So each
+ * piece is split into tags and text with markdown-it's own HTML tag grammar,
+ * each open tag is rebuilt by sanitize-html from its parsed attributes, a close
+ * tag stays if its tag is allowed, and text is escaped.
+ *
+ * Why that is safe whatever the grammar's edge cases: everything not taken as
+ * a tag is escaped (`<` becomes `&lt;`), so the browser cannot find a tag in it;
+ * everything taken as a tag is re-serialised by sanitize-html from what
+ * htmlparser2 parsed; comments, declarations and processing instructions are
+ * dropped. A disagreement between the grammar and a browser can only turn
+ * markup into visible text, never text into markup.
+ *
+ * Without a policy (no ConfigurationManager, or a malformed value) nothing an
+ * author wrote is allowed: the failure is closed. The pipeline's own
+ * constructs ({@link PIPELINE_HTML}) are always allowed.
+ *
+ * @module rendering/htmlPolicy
+ */
+/** The configuration key that declares the policy. */
+export declare const HTML_POLICY_KEY = "ngdpbase.markup.html-policy";
+/**
+ * The policy, read from configuration. There each list is a set kept as a map
+ * of `name: true` (#1612), so a layer adds or removes one entry without
+ * restating the rest; here it is the enabled names.
+ */
+export interface HtmlPolicy {
+    /** Tags an author may write. */
+    tags: string[];
+    /** Attributes allowed per tag; `*` applies to every allowed tag. */
+    attributes: Record<string, string[]>;
+    /** URL schemes allowed in URL attributes (`href`, `src`, …). Relative URLs are always allowed. */
+    schemes: string[];
+    /** A tag's own scheme set, used instead of `schemes` for that tag (`schemes-by-tag`). */
+    schemesByTag: Record<string, string[]>;
+}
+/**
+ * The configured value of `ngdpbase.markup.html-policy` as a policy, or null
+ * when it is absent or not an object — which allows no author HTML at all.
+ */
+export declare function asHtmlPolicy(value: unknown): HtmlPolicy | null;
+/**
+ * Author HTML as the policy allows it. `html` is one piece of author HTML —
+ * an html_block or html_inline token's content, or a raw block's text.
+ */
+export declare function filterAuthorHtml(html: string, policy: HtmlPolicy | null): string;
+/** One thing the policy does not allow, at an offset into the fragment. */
+export interface HtmlPolicyViolation {
+    message: string;
+    offset: number;
+}
+/**
+ * What {@link filterAuthorHtml} would drop from `html`, named for the author.
+ * Empty when the policy allows all of it.
+ */
+export declare function htmlPolicyViolations(html: string, policy: HtmlPolicy | null): HtmlPolicyViolation[];