@jwilleke/ngdpbase-types 5.25.0 → 5.26.0

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;

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -146,6 +146,20 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * cannot be asked by accident. The subject is the PIP's, resolved live.
      */
     userHoldsPermission(username: string, action: string): Promise<boolean>;
+    /**
+     * The usernames of every account that holds a permission, each asked through
+     * {@link userHoldsPermission} (#1813; was `utils/administrators.ts`). With
+     * `admin-system` this is "who are the administrators": the people an
+     * operator problem is reported to (#1431 7b, #1916), never a role name.
+     *
+     * An empty answer means "nobody to tell", and a caller sending a
+     * notification must then only log it: an empty `targetUsers` list means
+     * every user in NotificationManager.
+     *
+     * @returns The usernames, or null when there is no UserManager to list
+     *   accounts from (tests, a half-booted engine); treat that like nobody
+     */
+    usersHolding(action: string): Promise<string[] | null>;
     /**
      * The permissions a user's roles give them, for display (#1431 step 10).
      *

package/lib/src/types/Consent.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Consent to a site's documents (#1603): the shapes ConsentManager and its
+ * callers share, and what an add-on registers.
+ */
+/** Whose document it is: core's (`core`) or an add-on's slug. */
+export type ConsentScope = string;
+/** Where a person is asked to accept (#1603): `?scope=` (core when absent) and `?returnTo=`. */
+export declare const CONSENT_PATH = "/consent";
+/** The scope of core's own documents, `ngdpbase.consent.documents`. */
+export declare const CORE_CONSENT_SCOPE = "core";
+/**
+ * A document a person is asked to accept, as it stands now: a page whose
+ * front matter carries `version:` and `effective:`. Read from the page each
+ * time, never copied.
+ */
+export interface ConsentDocument {
+    /** The page's slug, which is also the document's id in a record (`terms-of-service`, `phr-privacy-policy`). */
+    id: string;
+    scope: ConsentScope;
+    /** The page's title, to show. */
+    title: string;
+    /** The page's `version:`, as a string. A change asks everyone again. */
+    version: string;
+    /** The page's `effective:` date (`YYYY-MM-DD`), or null when it names none. */
+    effective: string | null;
+}
+/** What a person saw when they accepted: each document and the version shown. */
+export interface ConsentSeen {
+    id: string;
+    version: string;
+}
+/**
+ * One acceptance, one line of the person's file. Append-only: a later
+ * version is a later line, nothing is rewritten.
+ */
+export interface ConsentRecord {
+    kind: 'accept';
+    document: string;
+    scope: ConsentScope;
+    version: string;
+    effective: string | null;
+    /** ISO 8601 time the person accepted. */
+    acceptedAt: string;
+    /**
+     * The account this was accepted on, by its creation time (#1937): a later
+     * account that takes the same username never inherits it.
+     */
+    account?: string;
+    /** Who and how: the account, where from, and the way they were asked (`sign-up`, `sign-in`, `add-on`). */
+    context: {
+        by: string;
+        how: string;
+        origin: string;
+        ipAddress?: string;
+    };
+}
+/** One document's state for a person, for "Your consents" on /profile. */
+export interface ConsentStatus {
+    document: ConsentDocument;
+    /** Their acceptance of the current version, or null: not accepted (never, or only an older version). */
+    current: ConsentRecord | null;
+    /** Their latest acceptance of any version, or null. */
+    latest: ConsentRecord | null;
+}
+/** What an add-on registers at load (#1603). */
+export interface AddonConsentRegistration {
+    /**
+     * Page slugs of the add-on's documents, each starting `<slug>-`
+     * (`phr-terms-of-service`, `phr-privacy-policy`). Shipped as the add-on's
+     * own pages, with `version:` and `effective:` front matter.
+     */
+    documents: string[];
+    /**
+     * URL path prefixes where a person uses the add-on in the browser
+     * (`/phr`). A person who has it on and has not accepted a changed version
+     * is asked there before going on. Optional: without it they are asked
+     * only when they next turn it on.
+     */
+    paths?: string[];
+}
+/**
+ * Thrown when a per-person add-on is turned on before its documents are
+ * accepted (#1603). `documents` names what is still to accept.
+ */
+export declare class ConsentRequiredError extends Error {
+    readonly scope: ConsentScope;
+    readonly documents: string[];
+    readonly name = "ConsentRequiredError";
+    constructor(scope: ConsentScope, documents: string[]);
+}

package/lib/src/types/express.d.ts

@@ -45,6 +45,12 @@ declare module 'express-session' {
         pendingRedirect?: string;
         /** A verified outside identity no account has connected, waiting for the person to sign in another way (#1743). */
         pendingConnection?: PendingConnection;
+        /**
+         * Set at sign-in when the person has core terms to accept at their current
+         * version (#1603); the consent gate holds the session to the prompt until
+         * they accept (or sign out). Cleared by the acceptance.
+         */
+        consentPending?: boolean;
         /** When this session last made a request, epoch ms — kept only while an idle timeout is set (#1546). */
         lastActivity?: number;
         /** When this session signed in, epoch ms: the start of `ngdpbase.session.max-age` (#1767). A re-authentication never moves it. */