@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/managers/PageManager.d.ts

@@ -184,10 +184,20 @@ export type PageRead<T> = {
 export interface PageConvertResult extends NcmResult {
     fixes: FixChange[];
 }
+/**
+ * A write refused because the page's `audience` leaves the writer out (#1964).
+ * Someone outside a page's audience may neither read nor edit it; an
+ * administrator (`admin-system`) is the exception. Routes answer it with 403.
+ */
+export declare class PageAudienceRefusedError extends Error {
+    readonly pageName: string;
+    constructor(pageName: string);
+}
 export declare class PageContentValidationError extends Error {
     readonly validationErrors: FilterValidationError[];
     constructor(pageName: string, validationErrors: FilterValidationError[]);
 }
+import { type PageAction } from '../utils/pageUrl.js';
 /** One vault page with data outside its vault (#1842), as the repair actions offer it. */
 export interface VaultRepairItem {
     owner: string;
@@ -796,10 +806,22 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * the normal getPage() path sanitises or normalises away. Returns null
      * when the page is unknown or the provider doesn't support raw reads.
      */
-    getRawPageContent(identifier: string): Promise<{
+    getRawPageContent(identifier: string, ctx: ActorContext): Promise<{
         filePath: string;
         content: string;
     } | null>;
+    /**
+     * The write door's audience check (#1964, operator 2026-10-23): someone a
+     * page's `audience` leaves out may neither read nor edit it, by any route —
+     * the editor, the raw editor, the API, a rename, a delete. The rule is the
+     * PIP's (`audienceAdmits`, the same one Tier 1 applies), asked with the
+     * caller's context; an administrator (`admin-system`) is admitted. A page
+     * that states no audience is not checked here — the routes ask the full
+     * page decision before they call the door.
+     *
+     * @throws PageAudienceRefusedError when the audience leaves `ctx` out
+     */
+    private assertAudienceAdmits;
     /**
      * Admin-override save (#689): the admin "Edit raw" textarea, split into
      * frontmatter and body and written through the door (#1462).
@@ -1289,6 +1311,29 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * @param action  - Legacy verb (`view`, `edit`) or policy action; default `view`
      */
     filterPagesFor(subject: ActorContext | PermissionSubject | null | undefined, names: readonly string[], action?: string): Promise<string[]>;
+    /**
+     * The `addon:<slug>` entries on a page that can match nobody (#1964): the
+     * slugs it names in `audience` or `access` that are not a loaded per-person
+     * add-on. Such an entry still decides — it refuses everyone it would have
+     * let in — so the author is told.
+     *
+     * @param metadata - The page's frontmatter
+     * @returns The slugs, in the order the page names them
+     */
+    unmatchableAddonAudience(metadata: Partial<PageFrontmatter> | null | undefined): string[];
+    /** Warn, naming the page and each slug, about {@link unmatchableAddonAudience}. */
+    private warnUnmatchableAddonAudience;
+    /**
+     * At startup, once add-ons have loaded (#1964): warn about every page whose
+     * `audience` or `access` names an add-on that can match nobody — unknown,
+     * not per-person, or not loaded.
+     *
+     * @returns Each page and slug warned about
+     */
+    reportUnmatchableAddonAudiences(): Promise<Array<{
+        page: string;
+        slug: string;
+    }>>;
     /**
      * Get all page titles (explicit alias for getAllPages)
      * Prefer this for new code that only needs page names.
@@ -1405,6 +1450,21 @@ declare class PageManager extends BaseManager implements CatalogSource {
         creator: string;
         store: string;
     } | null>;
+    /**
+     * The URL for `action` on the page named `pageName` (#1813): `/view/Main`,
+     * or for a vault page `/vaults/{owner}/{vault}/{title}` and its actions below
+     * it (#1456). The door an add-on asks; core's routes and views share the
+     * same `utils/pageUrl`. Reads no data and no config.
+     */
+    pageUrl(pageName: string, action?: PageAction): string;
+    /**
+     * The page name of `title` in `owner`'s vault `vault`, or in their default
+     * vault when no vault is given (#1813): `vaults/{owner}/{vault}/{title}`.
+     * The default vault is the system-category entry marked default, read live
+     * through ConfigurationManager (#1504). It names a page; it does not say the
+     * page exists or that anyone may open it.
+     */
+    privatePageName(owner: string, title: string, vault?: string): string;
     refreshPageList(): Promise<void>;
     /**
      * #1374: rewrite the provider's persistent page index from its last disk scan

package/lib/src/managers/PersonManager.d.ts

@@ -1,4 +1,4 @@
-import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import BaseManager, { type BackupFolder, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Person, PersonInput, PersonUpdate } from '../types/Person.js';
 import type { PersonProvider } from '../types/PersonProvider.js';
@@ -48,11 +48,13 @@ declare class PersonManager extends BaseManager {
     private linkOffers;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
-    /** Person records are in the backup (#1876), as `<stem>.persons.tar` beside the document. */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
-    restoreIsStaged(): boolean;
+    /** `ngdpbase.application.persons.storagedir`, resolved: where the records are. */
+    private configuredStorageDir;
+    /**
+     * Person records are in the backup (#1876), as `<stem>.persons.tar` beside the document. BackupManager backs it up, stages it in a site restore and puts it
+     * in place at the next start, before the records are read (#1985).
+     */
+    backupFolders(): BackupFolder[];
     getProvider(): PersonProvider | null;
     getById(id: string): Promise<Person | null>;
     getByIdentifier(identifier: string): Promise<Person | null>;

package/lib/src/managers/RoleManager.d.ts

@@ -1,4 +1,4 @@
-import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
+import BaseManager, { type BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Role, RoleUpdate } from '../types/Role.js';
 import type { RoleProvider } from '../types/RoleProvider.js';
@@ -33,15 +33,13 @@ declare class RoleManager extends BaseManager {
      * as is any other `additionalProperty` entry.
      */
     private stripCatalogueCopies;
+    /** `ngdpbase.application.roles.storagedir`, resolved: where the records are. */
+    private configuredStorageDir;
     /**
-     * Role membership is in the backup (#1876): the role records folder, as
-     * `<stem>.roles.tar` beside the document. Without it restored users would
-     * have no roles.
+     * Role membership is in the backup (#1876): the role records folder, as `<stem>.roles.tar` beside the document. Without it restored users would have no roles. BackupManager backs it up, stages it in a site restore and puts it
+     * in place at the next start, before the records are read (#1985).
      */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
-    restoreIsStaged(): boolean;
+    backupFolders(): BackupFolder[];
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
     getById(id: string): Promise<Role | null>;

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

@@ -4,7 +4,7 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import { ProviderInfo } from './BasePageProvider.js';
 import BaseProvider from './BaseProvider.js';
 import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
-import type { PartOutcome } from '../utils/siteRestore.js';
+import type { BackupArchiveTarget, ManagerRestoreOptions, SiteRestoreStaging, StagedRestoreAtStart } from '../managers/BaseManager.js';
 /**
  * File information for attachment uploads
  */
@@ -194,13 +194,13 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
      * streamed, bytes as stored. A provider without it can't be backed up whole,
      * and AttachmentManager's backup says so.
      */
-    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    backupFiles?(archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
     /** Stage the files and metadata from a backup for the next start, as part of a site restore (#1876). */
-    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, siteRestore: SiteRestoreStaging): Promise<{
         skippedVaults: string[];
     }>;
     /** What the start did with a staged restore of the files (#1876), once; null when there was none. */
-    takeRestoreAtStart?(): PartOutcome | null;
+    takeRestoreAtStart?(): StagedRestoreAtStart | null;
     /**
      * Shutdown the provider (cleanup resources)
      * @returns {Promise<void>}

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

@@ -0,0 +1,77 @@
+/**
+ * BaseBackupProvider - Base class for backup storage providers (Issue #170)
+ *
+ * Abstracts ONLY the backup storage target — where the assembled archive is
+ * written/read/listed/pruned. The *content* side (calling backup() on every
+ * manager, gzip, JSON, validation, retention policy, the auto-backup
+ * scheduler) stays in BackupManager and is unchanged: per-manager
+ * serialization was already provider-abstracted via `manager.backup()`, so
+ * #170 deliberately does not re-abstract it.
+ *
+ * Consistent with the engine-based Base*Provider family
+ * (Search/Audit/Cache/...). Unlike BaseLoggingProvider (#169), backup runs
+ * well after engine init, so the standard engine + initialize() shape applies.
+ *
+ * @class BaseBackupProvider
+ * @abstract
+ *
+ * @see {@link FileBackupProvider} for the default local-filesystem implementation
+ * @see {@link BackupManager} for usage
+ */
+import type { WikiEngine } from '../types/WikiEngine.js';
+import BaseProvider from './BaseProvider.js';
+/** Metadata for a stored backup object */
+export interface BackupObjectInfo {
+    filename: string;
+    path: string;
+    size: number;
+    created: Date;
+    modified: Date;
+}
+/** Provider metadata, consistent with the other Base*Provider classes */
+export interface BackupProviderInfo {
+    name: string;
+    version: string;
+    description: string;
+    features: string[];
+}
+declare abstract class BaseBackupProvider extends BaseProvider {
+    protected engine: WikiEngine;
+    protected initialized: boolean;
+    constructor(engine: WikiEngine);
+    /** Load config and prepare the storage target (e.g. ensure the directory). */
+    abstract initialize(): Promise<void>;
+    /** The resolved backup container location (directory / bucket prefix). */
+    abstract getBackupDirectory(): string;
+    /** Ensure the storage container exists. */
+    abstract ensureContainer(): Promise<void>;
+    /**
+     * Persist a backup object.
+     *
+     * @param filename - Object name (no path)
+     * @param data - Serialized (optionally gzip-compressed) payload
+     * @returns The full path / identifier of the written object
+     */
+    abstract writeBackup(filename: string, data: string | Buffer): Promise<string>;
+    /** Read a backup object by full path or bare filename. */
+    abstract readBackup(idOrPath: string): Promise<Buffer>;
+    /** Whether a backup object exists, by full path or bare filename. */
+    abstract backupExists(idOrPath: string): Promise<boolean>;
+    /** All objects in the container (BackupManager applies its own name filter). */
+    abstract listBackupObjects(): Promise<BackupObjectInfo[]>;
+    /** Delete a backup object by full path or bare filename. */
+    abstract removeBackup(idOrPath: string): Promise<void>;
+    /** Re-point the storage target at runtime (admin changes the directory). */
+    abstract setBackupDirectory(directory: string): Promise<void>;
+    /** Provider metadata. */
+    getProviderInfo(): BackupProviderInfo;
+    /**
+     * Free bytes at the storage target, or null when this provider can't tell
+     * (#1563). BackupManager compares it with the last backup's size before
+     * writing, and shows it on Admin → Backup.
+     */
+    freeSpace(): Promise<number | null>;
+    /** Health check — overridable by providers with remote dependencies. */
+    isHealthy(): Promise<boolean>;
+}
+export default BaseBackupProvider;

package/lib/src/providers/BaseBackupProvider.js

@@ -0,0 +1,52 @@
+/**
+ * BaseBackupProvider - Base class for backup storage providers (Issue #170)
+ *
+ * Abstracts ONLY the backup storage target — where the assembled archive is
+ * written/read/listed/pruned. The *content* side (calling backup() on every
+ * manager, gzip, JSON, validation, retention policy, the auto-backup
+ * scheduler) stays in BackupManager and is unchanged: per-manager
+ * serialization was already provider-abstracted via `manager.backup()`, so
+ * #170 deliberately does not re-abstract it.
+ *
+ * Consistent with the engine-based Base*Provider family
+ * (Search/Audit/Cache/...). Unlike BaseLoggingProvider (#169), backup runs
+ * well after engine init, so the standard engine + initialize() shape applies.
+ *
+ * @class BaseBackupProvider
+ * @abstract
+ *
+ * @see {@link FileBackupProvider} for the default local-filesystem implementation
+ * @see {@link BackupManager} for usage
+ */
+import BaseProvider from './BaseProvider.js';
+class BaseBackupProvider extends BaseProvider {
+    engine;
+    initialized;
+    constructor(engine) {
+        super();
+        this.engine = engine;
+        this.initialized = false;
+    }
+    /** Provider metadata. */
+    getProviderInfo() {
+        return {
+            name: 'BaseBackupProvider',
+            version: '1.0.0',
+            description: 'Base backup storage provider interface',
+            features: []
+        };
+    }
+    /**
+     * Free bytes at the storage target, or null when this provider can't tell
+     * (#1563). BackupManager compares it with the last backup's size before
+     * writing, and shows it on Admin → Backup.
+     */
+    async freeSpace() {
+        return null;
+    }
+    /** Health check — overridable by providers with remote dependencies. */
+    async isHealthy() {
+        return true;
+    }
+}
+export default BaseBackupProvider;

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

@@ -5,7 +5,7 @@ import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, Ass
 import type { CreativeWork } from '../types/Schema.js';
 import type { ActorContext } from '../context/ActorContext.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import { type PartOutcome } from '../utils/siteRestore.js';
+import type { BackupArchiveTarget, ManagerRestoreOptions, SiteRestoreStaging, StagedRestoreAtStart } from '../managers/BaseManager.js';
 import { type AttachmentFilesBackupData, type AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
 /**
  * Schema.org Person metadata
@@ -449,16 +449,16 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     /** Where the attachment files are, for their backup and staged restore (#1876). */
     private filePlaces;
     /** The files themselves, beside the backup document (#1876): the shared pool and every vault's, as stored. */
-    backupFiles(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    backupFiles(archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
     /**
      * Stage the files and the shared metadata from a backup for the next start
      * (#1876). The metadata is the document's; the live files and metadata are
      * not touched.
      */
-    stageFilesRestore(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+    stageFilesRestore(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, siteRestore: SiteRestoreStaging): Promise<{
         skippedVaults: string[];
     }>;
-    takeRestoreAtStart(): PartOutcome | null;
+    takeRestoreAtStart(): StagedRestoreAtStart | null;
     /**
      * Restore provider data from backup
      * @param backupData - Backup data

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

@@ -0,0 +1,34 @@
+/**
+ * FileBackupProvider - Default backup storage provider (Issue #170)
+ *
+ * Local-filesystem storage target for BackupManager. This is the I/O
+ * behaviour BackupManager performed inline before #170 (fs-extra against
+ * `ngdpbase.backup.directory`), extracted verbatim behind
+ * {@link BaseBackupProvider} so the storage backend is swappable without
+ * changing the orchestration/serialization logic.
+ *
+ * @class FileBackupProvider
+ * @extends BaseBackupProvider
+ */
+import type { WikiEngine } from '../types/WikiEngine.js';
+import BaseBackupProvider, { BackupObjectInfo, BackupProviderInfo } from './BaseBackupProvider.js';
+declare class FileBackupProvider extends BaseBackupProvider {
+    private backupDirectory;
+    constructor(engine: WikiEngine);
+    initialize(): Promise<void>;
+    getBackupDirectory(): string;
+    ensureContainer(): Promise<void>;
+    writeBackup(filename: string, data: string | Buffer): Promise<string>;
+    readBackup(idOrPath: string): Promise<Buffer>;
+    backupExists(idOrPath: string): Promise<boolean>;
+    listBackupObjects(): Promise<BackupObjectInfo[]>;
+    removeBackup(idOrPath: string): Promise<void>;
+    setBackupDirectory(directory: string): Promise<void>;
+    /** Free bytes on the backup directory's filesystem for this process (#1563). */
+    freeSpace(): Promise<number | null>;
+    getProviderInfo(): BackupProviderInfo;
+    /** Absolute paths (from listBackupObjects / createBackup) pass through; bare
+     *  names are resolved against the backup directory. */
+    private resolve;
+}
+export default FileBackupProvider;

package/lib/src/providers/FileBackupProvider.js

@@ -0,0 +1,116 @@
+/**
+ * FileBackupProvider - Default backup storage provider (Issue #170)
+ *
+ * Local-filesystem storage target for BackupManager. This is the I/O
+ * behaviour BackupManager performed inline before #170 (fs-extra against
+ * `ngdpbase.backup.directory`), extracted verbatim behind
+ * {@link BaseBackupProvider} so the storage backend is swappable without
+ * changing the orchestration/serialization logic.
+ *
+ * @class FileBackupProvider
+ * @extends BaseBackupProvider
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { statfs } from 'node:fs/promises';
+import BaseBackupProvider from './BaseBackupProvider.js';
+import { chmodSecretFile, ensureSecretDir, SECRET_FILE_MODE } from '../utils/secretFileMode.js';
+import logger from '../utils/logger.js';
+class FileBackupProvider extends BaseBackupProvider {
+    backupDirectory = '';
+    constructor(engine) {
+        super(engine);
+    }
+    async initialize() {
+        const configManager = this.engine.getManager('ConfigurationManager');
+        if (!configManager) {
+            throw new Error('FileBackupProvider requires ConfigurationManager');
+        }
+        // Uses getResolvedDataPath to support INSTANCE_DATA_FOLDER (same key/default
+        // BackupManager used before #170).
+        this.backupDirectory = configManager.getResolvedDataPath('ngdpbase.backup.directory', './data/backups');
+        await this.ensureContainer();
+        this.initialized = true;
+    }
+    getBackupDirectory() {
+        return this.backupDirectory;
+    }
+    async ensureContainer() {
+        if (this.backupDirectory) {
+            // #1560: backups hold the user store; owner-only where the filesystem allows.
+            const warning = ensureSecretDir(this.backupDirectory);
+            if (warning)
+                logger.warn(warning);
+        }
+    }
+    async writeBackup(filename, data) {
+        const target = path.join(this.backupDirectory, filename);
+        await fs.writeFile(target, data, { mode: SECRET_FILE_MODE });
+        const warning = chmodSecretFile(target); // #1560: the mode above is filtered by the umask
+        if (warning)
+            logger.warn(warning);
+        return target;
+    }
+    async readBackup(idOrPath) {
+        return fs.readFile(this.resolve(idOrPath));
+    }
+    async backupExists(idOrPath) {
+        return fs.pathExists(this.resolve(idOrPath));
+    }
+    async listBackupObjects() {
+        if (!this.backupDirectory)
+            return [];
+        const dir = this.backupDirectory;
+        const files = await fs.readdir(dir);
+        const objects = await Promise.all(files.map(async (filename) => {
+            const filePath = path.join(dir, filename);
+            let stats;
+            try {
+                stats = await fs.stat(filePath);
+            }
+            catch (err) {
+                // #1563: a file removed between the listing and its stat (a backup
+                // pruned meanwhile) is no longer there to list; anything else is a fault.
+                if (err.code === 'ENOENT')
+                    return null;
+                throw err;
+            }
+            return {
+                filename,
+                path: filePath,
+                size: stats.size,
+                created: stats.birthtime,
+                modified: stats.mtime
+            };
+        }));
+        return objects.filter((o) => o !== null);
+    }
+    async removeBackup(idOrPath) {
+        await fs.remove(this.resolve(idOrPath));
+    }
+    async setBackupDirectory(directory) {
+        this.backupDirectory = directory;
+        await this.ensureContainer();
+    }
+    /** Free bytes on the backup directory's filesystem for this process (#1563). */
+    async freeSpace() {
+        if (!this.backupDirectory)
+            return null;
+        const stats = await statfs(this.backupDirectory);
+        return Number(stats.bavail) * Number(stats.bsize);
+    }
+    getProviderInfo() {
+        return {
+            name: 'FileBackupProvider',
+            version: '1.0.0',
+            description: 'Local-filesystem backup storage (default)',
+            features: ['local-fs']
+        };
+    }
+    /** Absolute paths (from listBackupObjects / createBackup) pass through; bare
+     *  names are resolved against the backup directory. */
+    resolve(idOrPath) {
+        return path.isAbsolute(idOrPath) ? idOrPath : path.join(this.backupDirectory, idOrPath);
+    }
+}
+export default FileBackupProvider;

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

@@ -0,0 +1,18 @@
+import type { ConsentRecord } from '../types/Consent.js';
+declare class FileConsentProvider {
+    private readonly dir;
+    constructor(dir: string);
+    /** Create the folder owner-only; tighten one that is wider. */
+    initialize(): void;
+    /** The folder the records live in: what a backup copies. */
+    get directory(): string;
+    /** One file per account, named by the account's stored username. */
+    private fileFor;
+    /** Every record of `username`, oldest first; none when the file does not exist. Unreadable lines are reported and skipped. */
+    list(username: string): Promise<ConsentRecord[]>;
+    /** Add one record to `username`'s file, flushed to the device before returning. */
+    append(username: string, record: ConsentRecord): Promise<void>;
+    /** Remove `username`'s file (the account was deleted). True when there was one. */
+    remove(username: string): Promise<boolean>;
+}
+export default FileConsentProvider;

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

@@ -8,11 +8,11 @@
  * shared memory, which network filesystems do not provide, so the file's
  * location is checked first (`refuseNetworkFilesystem`).
  */
-import Database from 'better-sqlite3-multiple-ciphers';
+import type DatabaseDriver from 'better-sqlite3-multiple-ciphers';
 import BaseDatabaseProvider from './BaseDatabaseProvider.js';
 import type { ProviderDurability } from './BaseProvider.js';
 import { type Migration, type MigrationReport } from './sqliteMigrations.js';
-export type SqliteHandle = InstanceType<typeof Database>;
+export type SqliteHandle = InstanceType<typeof DatabaseDriver>;
 /** The lock wait when none is configured: the driver's own default, stated (#1710). */
 export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
 declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle> {

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -1,18 +1,19 @@
-/**
- * The application database as one SQLite file, encrypted with SQLCipher when a
- * key is given (#1536). Ported from yourPHR (yourphr#617).
- *
- * Opened and migrated in the constructor, so every provider built over the
- * handle sees a finished schema. WAL mode with `synchronous = FULL`: a
- * committed transaction is on the device before the call returns. WAL needs
- * shared memory, which network filesystems do not provide, so the file's
- * location is checked first (`refuseNetworkFilesystem`).
- */
-import Database from 'better-sqlite3-multiple-ciphers';
+import { createRequire } from 'node:module';
+import path from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import BaseDatabaseProvider from './BaseDatabaseProvider.js';
 import { runMigrations } from './sqliteMigrations.js';
 import { refuseNetworkFilesystem } from './sqliteLocation.js';
+/**
+ * The driver, loaded from the entry its package.json names (#1537). Run from
+ * source by tsx — the operator scripts, `npm run audit:verify -- --database` —
+ * the bare package name follows tsconfig's `paths`, which maps it to the type
+ * declarations, for `import`, `require` and `require.resolve` alike; its
+ * `package.json` is not mapped.
+ */
+const requireHere = createRequire(import.meta.url);
+const driverPackage = requireHere.resolve('better-sqlite3-multiple-ciphers/package.json');
+const Database = requireHere(path.join(path.dirname(driverPackage), requireHere(driverPackage).main));
 /** The lock wait when none is configured: the driver's own default, stated (#1710). */
 export const DEFAULT_BUSY_TIMEOUT_MS = 5000;
 class SqliteDatabaseProvider extends BaseDatabaseProvider {

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

@@ -1,4 +1,5 @@
-import { type PartOutcome } from '../utils/siteRestore.js';
+import type { BackupArchiveTarget, ManagerRestoreOptions, SiteRestoreStaging, StagedRestoreAtStart } from '../managers/BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
 import { type PrivateStoreLayout } from '../utils/privateStorePath.js';
 /** Where the attachment files live on this site. */
 export interface AttachmentFilePlaces {
@@ -33,7 +34,7 @@ export interface AttachmentFilesBackupOutcome {
     warnings: string[];
 }
 /** Write the attachment files beside the backup document: the pool, then every vault's. Never base64, never whole in memory. */
-export declare function backupAttachmentFiles(places: AttachmentFilePlaces, directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+export declare function backupAttachmentFiles(places: AttachmentFilePlaces, archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
 /**
  * Stage the attachment files from a backup for the next start, and record
  * the part in the site restore. All or nothing: on any failure every staged
@@ -41,7 +42,7 @@ export declare function backupAttachmentFiles(places: AttachmentFilePlaces, dire
  *
  * @returns the vaults the backup holds that this site doesn't have (not staged).
  */
-export declare function stageAttachmentFiles(places: AttachmentFilePlaces, directory: string, data: AttachmentFilesBackupData, metadataJson: string, siteRestore: string): Promise<{
+export declare function stageAttachmentFiles(places: AttachmentFilePlaces, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, data: AttachmentFilesBackupData, metadataJson: string, siteRestore: SiteRestoreStaging): Promise<{
     skippedVaults: string[];
 }>;
 /**
@@ -49,4 +50,4 @@ export declare function stageAttachmentFiles(places: AttachmentFilePlaces, direc
  * read: only the pool, its metadata file and vault attachment paths may be
  * replaced, whatever the manifest says.
  */
-export declare function applyAttachmentFilesAtStart(places: AttachmentFilePlaces, siteRestore: string): PartOutcome | null;
+export declare function applyAttachmentFilesAtStart(engine: WikiEngine, places: AttachmentFilePlaces): Promise<StagedRestoreAtStart | null>;

package/lib/src/providers/databaseMigrations.js

@@ -42,6 +42,51 @@ const DATABASE_MIGRATIONS = [
         up: (db) => {
             db.exec('ALTER TABLE job_state ADD COLUMN rule TEXT');
         }
+    },
+    {
+        // #1537: the audit log in the database. `row_id` is the order records were
+        // written, which is chain order; `seq` repeats after a chain restart, so
+        // it is not the key. `record` is the stamped record exactly as hashed;
+        // the other columns are copies of its fields for the indexes. A retention
+        // checkpoint holds the seq and hash of the last record it removed, so
+        // what remains verifies from it.
+        id: '20261022120000',
+        description: 'audit log: audit_events, audit_checkpoints',
+        up: (db) => {
+            db.exec(`CREATE TABLE audit_events (
+        row_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE,
+        seq INTEGER NOT NULL,
+        prev_hash TEXT NOT NULL,
+        hash TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        user TEXT,
+        actor TEXT,
+        owner TEXT,
+        resource TEXT,
+        action TEXT,
+        result TEXT,
+        severity TEXT,
+        record TEXT NOT NULL
+      )`);
+            db.exec('CREATE INDEX audit_events_by_time ON audit_events (timestamp)');
+            db.exec('CREATE INDEX audit_events_by_type ON audit_events (event_type, timestamp)');
+            db.exec('CREATE INDEX audit_events_by_user ON audit_events (user, timestamp)');
+            db.exec('CREATE INDEX audit_events_by_actor ON audit_events (actor, timestamp)');
+            db.exec('CREATE INDEX audit_events_by_owner ON audit_events (owner, timestamp)');
+            db.exec('CREATE INDEX audit_events_by_resource ON audit_events (resource, timestamp)');
+            db.exec(`CREATE TABLE audit_checkpoints (
+        checkpoint_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        through_row INTEGER NOT NULL,
+        seq INTEGER NOT NULL,
+        hash TEXT NOT NULL,
+        removed INTEGER NOT NULL,
+        cutoff TEXT NOT NULL,
+        retention_days INTEGER NOT NULL,
+        created_at TEXT NOT NULL
+      )`);
+        }
     }
 ];
 export default DATABASE_MIGRATIONS;