@jwilleke/ngdpbase-types 5.21.0 → 5.22.0

package/lib/src/providers/sqliteBackup.js

@@ -307,12 +307,7 @@ export function applyStagedRestore(applicationFile, allowed) {
             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 };
-    };
+    const setAside = (reason) => setAsideStagedRestore(applicationFile, reason);
     let manifest;
     try {
         manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
@@ -351,6 +346,21 @@ export function applyStagedRestore(applicationFile, allowed) {
     unlinkSync(manifestFile);
     return { applied };
 }
+/**
+ * Set a staged restore aside without applying any of it (#1876): every
+ * `*.db.staged` beside the application database and the manifest become
+ * `*.incomplete`. Used when the site restore it belongs to is not applied.
+ */
+export function setAsideStagedRestore(applicationFile, reason) {
+    const manifestFile = manifestPath(applicationFile);
+    const dir = path.dirname(applicationFile);
+    const staged = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.db.staged')).map((f) => path.join(dir, f)) : [];
+    for (const f of staged)
+        move(f, `${f}.incomplete`);
+    if (existsSync(manifestFile))
+        move(manifestFile, `${manifestFile}.incomplete`);
+    return { applied: [], refused: reason };
+}
 /** A rename; a copy and unlink when the two paths are on different devices. */
 function move(from, to) {
     try {

package/lib/src/security/permissions.generated.d.ts

@@ -22,6 +22,10 @@ export type CorePermission =
  | 'comment-create'
 /** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
  | 'config-manage'
+/** Create, edit, delete and link contacts: persons (with or without an account) and organizations, and a person's affiliations, through PersonManager and OrganizationManager (#1930). Reading them is contact-read. Admins by default; an add-on grants it to its own roles in its own policy */
+ | 'contact-manage'
+/** List, search and view contacts: persons (with or without an account) and organizations, and their affiliations, through PersonManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Admins and demo admins by default; an add-on grants it to its own roles in its own policy */
+ | 'contact-read'
 /** Browse and view the media library (not delegated to anonymous visitors) */
  | 'media-read'
 /** Create new pages */

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

@@ -6,6 +6,14 @@
  * while AttachmentManager / MediaManager remain thin wrappers.
  */
 import type { ActorContext } from '../context/ActorContext.js';
+/**
+ * What an attachment record says when it was stored with no uploader, in the
+ * pool's `author.name`, and what `uploadedBy` shows for a record with none.
+ * Only records written before #1926 carry it: a new upload names its
+ * uploader's username or is refused. Not a user; the files layer reads it as
+ * "no owner" (#1852).
+ */
+export declare const UNKNOWN_UPLOADER = "Unknown";
 /**
  * Capabilities that an AssetProvider may declare.
  * Used to advertise which optional operations the provider supports.
@@ -207,6 +215,8 @@ export interface AssetRecord {
     author?: string;
     /** ISO 8601 timestamp of the last metadata or file modification — schema.org/dateModified */
     dateModified?: string;
+    /** Username of whoever last changed it, when the provider records one — schema.org/editor */
+    editor?: string;
     /** Licensing and rights information */
     usageRights?: AssetUsageRights;
     /** Download counts and access statistics */

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

@@ -116,6 +116,11 @@ export interface WikiConfig {
      */
     'ngdpbase.auth.throttle.max-lock-minutes': number;
     'ngdpbase.mail.rate-limit.enabled': boolean;
+    /**
+     * Outbound email failures: one administrator notice per this many minutes,
+     * counting every failure inside it (#1916). Default: 60.
+     */
+    'ngdpbase.mail.failure-notice.window-minutes': number;
     /**
      * Anti-spam: max submissions per IP per `window-minutes` window before
      * the 429 trips (#670 Phase E). Default: 5.
@@ -305,6 +310,12 @@ export interface ApplicationOrganizationConfig {
     'ngdpbase.application.persons.provider.default': string;
     /** Active Person provider class (lowercased; falls back to .default) */
     'ngdpbase.application.persons.provider': string;
+    /** #1930: the most results `PersonManager.search` returns when the caller gives no limit */
+    'ngdpbase.application.persons.search.limit': number;
+    /** #1930: minutes the emailed "Is this you?" sign-up link stays usable */
+    'ngdpbase.application.persons.link-offer.ttl-minutes': number;
+    /** #1930: the most results `OrganizationManager.search` returns when the caller gives no limit */
+    'ngdpbase.application.organization.search.limit': number;
     /** Storage directory for OrganizationRole JSON files (one per (org, namedPosition) pair) */
     'ngdpbase.application.roles.storagedir': string;
     /** Default Role provider class (lowercased) */

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

@@ -71,6 +71,13 @@ export interface Organization {
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
 }
+/**
+ * What a caller gives `OrganizationManager.create` (#1930): the fields, with
+ * `@id` optional (it defaults to the `url`, else a new `urn:uuid:`).
+ */
+export type OrganizationInput = Partial<Organization> & {
+    name: string;
+};
 /**
  * Patch shape for update operations.
  * `@context`/`@type` are immutable; `@id` cannot be changed via update.

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

@@ -6,8 +6,9 @@
  * (where the uuid matches the v4 segment of `@id`).
  *
  * `@id` uses the urn:uuid:<v4> form because persons typically lack a
- * canonical web URL. `identifier` matches `User.username` so existing auth
- * records link cleanly to a Person.
+ * canonical web URL. `identifier` is the person's account (`User.username`)
+ * when they have one, and `person:<uuid>` when they do not (#1930) — a form
+ * no username may take (`ACCOUNTLESS_PERSON_PREFIX`, `src/utils/username.ts`).
  *
  * No embedded role-records — those live in the future person-contacts
  * addon (#602) and are folded in at JSON-LD export time.
@@ -15,6 +16,18 @@
  * @see https://schema.org/Person
  */
 import type { PostalAddress, ContactPoint } from './Organization.js';
+/**
+ * One organization a person is affiliated with (#1930): schema.org
+ * `affiliation`, with the person's role or title there when one is known.
+ * The organization is named by its `@id`; OrganizationManager lists an
+ * organization's people by reading these, so the link is stored once, here.
+ */
+export interface PersonAffiliation {
+    /** The organization's `@id`. */
+    organization: string;
+    /** The person's role or title there (schema.org `roleName`), when known. */
+    role?: string;
+}
 /**
  * Canonical Person record.
  *
@@ -26,7 +39,7 @@ export interface Person {
     '@type': 'Person';
     /** urn:uuid:<v4> */
     '@id': string;
-    /** Matches User.username so auth records link to this Person */
+    /** The account's username, or `person:<uuid>` for a person with no account (#1930). */
     identifier: string;
     /** Display name */
     name?: string;
@@ -46,6 +59,8 @@ export interface Person {
     image?: string;
     /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
     sameAs?: string[];
+    /** Organizations this person is affiliated with, each with an optional role (#1930). */
+    affiliation?: PersonAffiliation[];
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
 }
@@ -54,3 +69,12 @@ export interface Person {
  * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
+/**
+ * What a caller gives `PersonManager.create` (#1930): the person's fields.
+ * `identifier` is left out for a person with no account (one is generated);
+ * UserManager passes the account's username when it creates the person for a
+ * new account.
+ */
+export type PersonInput = PersonUpdate & {
+    identifier?: string;
+};

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

@@ -18,6 +18,12 @@ export interface PersonProvider extends BaseProvider {
     getByIdentifier(identifier: string): Promise<Person | null>;
     /** Persist a new Person. Returns the stored record. */
     create(person: Person): Promise<Person>;
+    /**
+     * Write the whole record in place of the one with the same `@id` (#1930).
+     * The only write that may change `identifier`: PersonManager uses it to join
+     * a person to an account.
+     */
+    replace(person: Person): Promise<Person>;
     /** Apply a partial update by `@id`. Returns the updated record, or null if not found. */
     update(id: string, patch: PersonUpdate): Promise<Person | null>;
     /** Delete by `@id`. Returns true if a record was removed. */

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

@@ -8,6 +8,7 @@ import { WikiConfig } from './Config.js';
 import type { Logger } from 'winston';
 import type { Application, Request, RequestHandler, Router, RouterOptions } from 'express';
 import type express from 'express';
+import type { MaintenanceState } from '../utils/maintenanceState.js';
 /**
  * All known manager names as a union type
  * Use with getManager() for type-safe access when combined with explicit type parameter
@@ -95,28 +96,15 @@ export interface WikiEngine {
      */
     shutdown(): Promise<void>;
     /**
-     * Record a configuration value that cannot be used (#1152).
-     *
-     * Recorded rather than thrown so `initialize()` finishes and the admin
-     * screens exist — the instance then serves maintenance mode with a route to
-     * the repair, instead of exiting and leaving the filesystem as the only way
-     * back. Only for values an administrator can fix through the admin UI; a
-     * failure of the machinery needed to serve that UI is fatal and still throws.
-     * Also a site-critical add-on that did not load (#1883, operator
-     * 2026-10-18): its fix may lie outside the UI (a key in the instance .env),
-     * and the admin notification says so.
-     */
-    blockConfiguration(reason: string, options?: {
-        publicMessage?: string;
-    }): void;
-    /** Configuration values that could not be used, in the order found (#1152). */
-    getBlockingConditions(): readonly string[];
-    /**
-     * What visitors see in place of the reasons, when a reason was recorded with
-     * a `publicMessage` (#1883: a site-critical add-on that did not load); null
-     * when every reason may be shown.
+     * Whether the site is in maintenance mode, and why (#1906): the one door.
+     * A manager that needs the site closed calls `maintenance.enter(reason,
+     * { message?, estimatedDuration? })`, and `maintenance.leave(reason)` when
+     * the reason clears. Reasons are for administrators only; visitors get
+     * `maintenance.visitorView(configManager)`. Replaces `blockConfiguration`
+     * (#1152), still recorded rather than thrown so `initialize()` finishes and
+     * `/admin`, `/login` and `/logout` stay reachable.
      */
-    getPublicBlockingMessage(): string | null;
+    readonly maintenance: MaintenanceState;
     /**
      * Get all registered manager names
      * @returns Array of manager names

package/lib/src/utils/addonPageSync.d.ts

@@ -31,6 +31,30 @@ export declare function evaluateSeededAddonPage(args: {
     liveContent: string;
     storedHash: string | undefined;
 }): SeededAddonPageStatus;
+/**
+ * How a shipped item's sync status reads on an admin screen: the status words
+ * and the edit protection of Admin → Required Pages, which every screen that
+ * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`;
+ * shipped forms, #1918).
+ *
+ *  - `status` — `modified` when the live copy differs from what ships,
+ *    `current` when it is the same.
+ *  - `userModified` — edited on this site: Sync does not replace it; Force Sync
+ *    does, after a confirm.
+ */
+export interface SyncRowState {
+    status: 'current' | 'modified';
+    userModified: boolean;
+}
+/**
+ * The one mapping from `evaluateSeededAddonPage`'s answer to the admin screen's
+ * words (#1918). `userModifiedFlag` is a page's explicit `user-modified`
+ * frontmatter, which marks it edited even when the hash cannot tell.
+ *
+ * @param seedStatus - `evaluateSeededAddonPage`'s answer for the live copy
+ * @param userModifiedFlag - The live copy is explicitly marked edited
+ */
+export declare function syncRowState(seedStatus: SeededAddonPageStatus, userModifiedFlag?: boolean): SyncRowState;
 /**
  * Default edit access for a page ngdpbase ships (#971, #1411): a `general`
  * page is instance-owned and gets no stamp; any other category — system,

package/lib/src/utils/administrators.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who an administrator notification goes to.
+ *
+ * __An administrator is whoever holds `admin-system`__, asked per user through
+ * the policy (#1431 7b) — never a role name. Used by every report that must
+ * reach administrators and nobody else: a damaged page (#1431 step 7) and
+ * failing outbound email (#1916).
+ *
+ * An empty answer means "nobody to tell", and the caller must then log only:
+ * an empty `targetUsers` list means ALL users in NotificationManager, which
+ * would announce an operator problem to every reader.
+ *
+ * Null when the managers needed to answer are not registered (tests, a
+ * half-booted engine) — the caller treats that like "nobody to tell".
+ */
+type EngineLike = {
+    getManager: (name: string) => unknown;
+} | null | undefined;
+/** Usernames of every user who holds `admin-system`; null when it cannot be asked. */
+export declare function administratorUsernames(engine: EngineLike): Promise<string[] | null>;
+export {};

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -36,6 +36,8 @@ export declare const AUDIT_EVENT: {
     readonly BACKUP_CREATE: "backup-create";
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE: "backup-restore";
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    readonly BACKUP_RESTORE_APPLIED: "backup-restore-applied";
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE_CANCEL: "backup-restore-cancel";
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -48,6 +50,8 @@ export declare const AUDIT_EVENT: {
     readonly CONFIG_CHANGE: "config-change";
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     readonly CONFIG_RESET: "config-reset";
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    readonly CONTACT_MANAGE: "contact-manage";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** A background job finished successfully */

package/lib/src/utils/auditEventNames.generated.js

@@ -43,6 +43,8 @@ export const AUDIT_EVENT = {
     BACKUP_CREATE: 'backup-create',
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     BACKUP_RESTORE: 'backup-restore',
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    BACKUP_RESTORE_APPLIED: 'backup-restore-applied',
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     BACKUP_RESTORE_CANCEL: 'backup-restore-cancel',
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -55,6 +57,8 @@ export const AUDIT_EVENT = {
     CONFIG_CHANGE: 'config-change',
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     CONFIG_RESET: 'config-reset',
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    CONTACT_MANAGE: 'contact-manage',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** A background job finished successfully */

package/lib/src/utils/backupCrypto.d.ts

@@ -0,0 +1,28 @@
+import { Transform } from 'node:stream';
+/** The first bytes of every encrypted backup file. */
+export declare const BACKUP_FILE_MAGIC: Buffer<ArrayBuffer>;
+/** What an encrypted backup file's name ends with. */
+export declare const ENCRYPTED_SUFFIX = ".enc";
+/** A backup file made under a different backup key than the one set now. */
+export declare class BackupKeyMismatchError extends Error {
+    readonly fileFingerprint: string;
+    readonly keyFingerprint: string;
+    constructor(fileFingerprint: string, keyFingerprint: string);
+}
+/** Whether these bytes (a file's first) are an encrypted backup file. */
+export declare function isEncryptedBackup(head: Buffer): boolean;
+/** Whether the file on disk is an encrypted backup file, read from its first bytes only. */
+export declare function fileIsEncrypted(file: string): Promise<boolean>;
+/** A stream that encrypts what is written to it under `backupKey`. */
+export declare function encryptStream(backupKey: string): Transform;
+/**
+ * A stream that decrypts an encrypted backup file written to it. Fails —
+ * naming why — on a file that is not one, a different backup key
+ * ({@link BackupKeyMismatchError}), any record that does not verify, and a
+ * file cut short or with bytes after its last record.
+ */
+export declare function decryptStream(backupKey: string): Transform;
+/** Encrypt a whole buffer (the backup document, already in memory). */
+export declare function encryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;
+/** Decrypt a whole buffer. */
+export declare function decryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;

package/lib/src/utils/backupKey.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * Its own secret, not the database key: the copy that travels and the copy
+ * that stays should not fall to the same compromise. Never a config key.
+ */
+export declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export declare function backupKeyFingerprint(key: string): string;
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export declare const LEFT_OUT_FOR_NO_KEY = "NGDPBASE_BACKUP_KEY is not set, so ";
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export declare function isLeftOutForNoKey(message: string): boolean;
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export declare function currentBackupKey(): string;

package/lib/src/utils/backupKey.js

@@ -0,0 +1,37 @@
+/**
+ * The backup key (#1723, #1561, #1876): the one secret every encrypted part of
+ * a backup is made under — the database files (SQLCipher, `sqliteBackup.ts`),
+ * and the backup document, the file archives and the credentials store
+ * (`backupCrypto.ts`). One declaration here; DatabaseManager and the file
+ * parts read it from this module.
+ */
+import { createHmac } from 'node:crypto';
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * Its own secret, not the database key: the copy that travels and the copy
+ * that stays should not fall to the same compromise. Never a config key.
+ */
+export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export function backupKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
+}
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export const LEFT_OUT_FOR_NO_KEY = `${BACKUP_KEY_ENV} is not set, so `;
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export function isLeftOutForNoKey(message) {
+    return message.startsWith(LEFT_OUT_FOR_NO_KEY);
+}
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export function currentBackupKey() {
+    return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+}

package/lib/src/utils/contactAccess.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The contacts door's one decision and its one record (#1930).
+ *
+ * PersonManager and OrganizationManager are the enforcement points for
+ * contacts. Both ask the PDP the same two questions with the caller's
+ * context: `contact-read` to list, search or view, `contact-manage` to
+ * create, change, delete or link; and both record each change as the
+ * `contact-manage` audit event. That rule lives here once, so the two doors
+ * cannot drift (operator, 2026-10-20).
+ *
+ * A refusal is thrown as {@link ContactRefusedError}, carrying the decision.
+ * A route turns it into the answer with `ApiContext.enforceDeny(err.permission,
+ * err.decision)`, the one place a refusal is shaped (#1431); the door never
+ * builds an HTTP answer itself.
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+import type { CorePermission } from '../security/permissions.generated.js';
+import type { Decision } from '../types/Policy.js';
+type EngineLike = {
+    getManager: <T = unknown>(name: string) => T | null | undefined;
+};
+/** What a contacts door asks: `read` to list, search or view; `manage` to change. */
+export declare const CONTACT_PERMISSION: {
+    readonly read: "contact-read";
+    readonly manage: "contact-manage";
+};
+/** A contacts door said no. `permission` is what was refused; `decision` is the PDP's answer. */
+export declare class ContactRefusedError extends Error {
+    readonly permission: string;
+    readonly decision: Decision;
+    constructor(permission: string, decision: Decision);
+}
+/**
+ * Throws {@link ContactRefusedError} unless `ctx` may do `kind` (`read` asks
+ * `contact-read`, `manage` asks `contact-manage`), and each of `also` (a link
+ * to an account also asks `user-edit`). A missing context or decision point
+ * refuses: closed, never open.
+ */
+export declare function requireContactPermission(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, also?: readonly CorePermission[]): Promise<void>;
+/** What a contacts record says was done. Names fields, never their values. */
+export interface ContactChange {
+    kind: 'person' | 'organization';
+    operation: 'create' | 'update' | 'delete' | 'link';
+    id: string;
+    fields?: string[];
+    /** For a link: the account joined to the person. */
+    account?: string;
+    /** For a link: how it was confirmed, `admin` or `email`. */
+    via?: 'admin' | 'email';
+}
+/**
+ * Record a contacts change as `contact-manage`, under the caller's context.
+ * `continue`: a lost record is counted, the change stands. A system context
+ * goes through `recordSystemAction`, so the bootstrap admin's person, made
+ * before the audit sink is up, is recorded once it is.
+ */
+export declare function recordContactChange(engine: EngineLike, ctx: ActorContext, change: ContactChange): Promise<void>;
+export {};

package/lib/src/utils/databaseKey.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export declare const DATABASE_KEY_ENV = "NGDPBASE_DATABASE_KEY";

package/lib/src/utils/databaseKey.js

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';

package/lib/src/utils/directoryBackup.d.ts

@@ -0,0 +1,78 @@
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from '../managers/BaseManager.js';
+import { siteRestoreFile, type PartOutcome } from './siteRestore.js';
+/** A folder part's `data` in the backup document. */
+export interface DirectoryBackupData {
+    format: 1;
+    /** The archive beside the document: `<stem>.<part>.tar`, or `.tar.enc` when encrypted. */
+    archive: string;
+    files: number;
+    bytes: number;
+    /** `backupKeyFingerprint()` of the key the archive is encrypted under; absent when it is not encrypted. */
+    keyFingerprint?: string;
+}
+/** Whether `name` is a bare archive name in the backup directory, never a path. */
+export declare function isArchiveName(name: unknown): name is string;
+/**
+ * The name and key for one archive of a backup: encrypted under the backup
+ * key when it is set (#1561), plain otherwise. BackupManager says, once per
+ * backup, that a backup without the key is not encrypted.
+ */
+export declare function archiveTarget(stem: string, part: string): {
+    archive: string;
+    backupKey?: string;
+    keyFingerprint?: string;
+};
+/**
+ * The key to read an archive of a backup with, checked against the
+ * fingerprint the backup recorded: a backup made under another key is
+ * refused before anything is staged. None for a backup that was not
+ * encrypted, which is then read as the plain archive it says it is.
+ */
+export declare function archiveReadKey(manager: string, data: {
+    keyFingerprint?: string;
+}): string | undefined;
+/**
+ * Back the folder up beside the document BackupManager is writing. Throws
+ * outside BackupManager: the files go beside a document, never into it.
+ * `exclude` leaves out a path relative to the folder (posix form).
+ */
+export declare function backupDirectoryPart(manager: string, part: string, folder: string | null, options?: ManagerBackupOptions, extra?: {
+    exclude?: (relative: string) => boolean;
+}): Promise<BackupData>;
+/**
+ * Stage the folder from a backup for the next start: the archive is
+ * extracted to `<folder>.staged`, and the swap recorded in the site restore.
+ * Throws — staging nothing — outside a site restore, for a backup without
+ * this part, or for an archive that is missing, unsafe, or under another key.
+ */
+export declare function stageDirectoryPart(manager: string, folder: string | null, backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+/**
+ * Put a staged restore of the folder in place, at start, before the manager
+ * reads it. Loud when something was staged but not applied.
+ */
+export declare function applyDirectoryPartAtStart(manager: string, folder: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;
+/**
+ * Back one file up beside the document, encrypted under the backup key, as
+ * `<stem>.<part>.tar.enc`. With `requireKey` and no key the file is left out:
+ * `data` is null and a warning says why, so BackupManager reports the backup
+ * incomplete (#1876: the credentials store is never in a backup unencrypted).
+ */
+export declare function backupFilePart(manager: string, part: string, file: string | null, options: ManagerBackupOptions | undefined, { requireKey, what }: {
+    requireKey: boolean;
+    what: string;
+}): Promise<{
+    data: DirectoryBackupData | null;
+    warnings: string[];
+    note?: string;
+}>;
+/**
+ * Stage one file from a backup as `<file>.staged`, and record the swap. When
+ * the file was absent at backup time the archive holds nothing, and
+ * `whenAbsent` is staged in its place (an empty store), so the restore still
+ * puts the site back as it was.
+ */
+export declare function stageFilePart(manager: string, file: string, data: DirectoryBackupData, options: ManagerRestoreOptions | undefined, { whenAbsent }: {
+    whenAbsent: string;
+}): Promise<void>;
+/** Put a staged restore of one file in place, at start, before the manager reads it. */
+export declare function applyFilePartAtStart(manager: string, file: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;

package/lib/src/utils/emailForLog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * emailForLog — the one way an email address reaches the server log (#1916).
+ *
+ * Rule (operator, 2026-10-20): a full email address never reaches the server
+ * log. A log line names the address's domain only. Audit records are not the
+ * server log and keep full addresses; do not use these helpers on them.
+ */
+/**
+ * The domain(s) of one address or a comma-separated list, lower-cased:
+ * `"Bob <bob@Example.org>, ann@x.io"` → `"example.org,x.io"`. A value
+ * without an `@` (or an empty one) reads as `unknown`.
+ */
+export declare function emailDomain(to: string | null | undefined): string;
+/**
+ * Any address inside free text (an SMTP error often quotes the rejected one)
+ * cut to its domain: `bob@example.org` → `…@example.org`.
+ */
+export declare function redactEmailAddresses(text: string): string;
+/** An error's message, with any address in it cut to its domain. */
+export declare function errorForLog(err: unknown): string;