@jwilleke/ngdpbase-types 5.24.0 → 5.26.0

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. */

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

@@ -10,6 +10,15 @@
  * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
  *   this add-on declares in its own `config/default-config.json`, so one
  *   add-on cannot write records that look like another's or like core's;
+ * - `systemContext(reason)` is bound to the running engine, so the system
+ *   principal's name comes from core (`NGDPBASE_SYSTEM_USER`), never from
+ *   the add-on (#1973);
+ * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
+ *   bound to its slug, so it can never set another add-on's;
+ * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
+ *   are core's own pure functions, handed on unchanged, so an add-on never
+ *   imports them from `dist/` (#1813);
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -17,9 +26,14 @@
  */
 import type { Logger } from 'winston';
 import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
-import { actorOf } from '../context/ActorContext.js';
-import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { actorOf, type ActorContext } from '../context/ActorContext.js';
+import { jobContextFromRequest, jobContextFromSystem, type JobContext } from '../context/JobContext.js';
+import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
+import { resolveEgressPolicy } from '../http/egressPolicy.js';
+import { validateUrl } from '../http/ssrf.js';
+import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
+import { isAtLeast } from './version.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 /** The values core offers an add-on, under the names they were imported as. */
@@ -32,9 +46,39 @@ export interface AddonHost {
     readonly actorOf: typeof actorOf;
     readonly jobContextFromRequest: typeof jobContextFromRequest;
     readonly jobContextFromSystem: typeof jobContextFromSystem;
+    /**
+     * The context the add-on's own boot work runs under (#1973): core's system
+     * principal, with `reason` saying what and why, for the record. Pass it
+     * where a manager door asks for a context at start, such as
+     * `FormsDataManager.registerShippedForm`.
+     */
+    readonly systemContext: (reason: string) => JobContext;
     readonly logger: Logger;
     readonly guardedFetch: typeof guardedFetch;
+    /**
+     * #1963: turn this per-person add-on on (`true`) or off (`false`) for the
+     * person `ctx` acts as: their preference `<slug>.enabled`. Pass the context
+     * you were given (a profile hook's `ctx`). Refused when the add-on's manifest
+     * does not say `perPerson: true`, or the person may not manage their profile.
+     */
+    readonly setEnabledForPerson: PersonSwitchSetter;
+    /**
+     * The site's egress policy, read through `read` (a `ConfigurationManager.getProperty`
+     * reader) each time it is called, so an operator tightening it applies at once.
+     * Hand its `policy` to `guardedFetch` or `validateUrl`.
+     */
+    readonly resolveEgressPolicy: typeof resolveEgressPolicy;
+    /** Whether a URL may be fetched under an egress policy, before any socket: http(s) and an allowed literal address. */
+    readonly validateUrl: typeof validateUrl;
+    /** An Elasticsearch client whose every connection is judged by the egress policy; the only way to build one. */
+    readonly createGuardedElasticsearchClient: typeof createGuardedElasticsearchClient;
+    /** The one boot-time line for an Elasticsearch node the egress policy refuses. */
+    readonly refusedNodeMessage: typeof refusedNodeMessage;
+    /** Whether an `x.y.z` version is at least another; throws on a version that is not `x.y.z`. */
+    readonly isAtLeast: typeof isAtLeast;
 }
+/** Sets one add-on's per-person switch; core binds the slug when it builds the host (#1963). */
+export type PersonSwitchSetter = (ctx: ActorContext, on: boolean) => Promise<void>;
 /**
  * The audit event names one add-on declares: the permission entries carrying
  * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
@@ -47,5 +91,9 @@ export declare function addonDeclaredAuditEvents(addonDefaults: Record<string, u
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - That add-on's own default-config.json, as folded into
  *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ * @param setEnabledForPerson - This add-on's switch setter, slug already bound
+ *   (`AddonsManager` supplies it); without one, the host's setter refuses
+ * @param engine - The running engine, which names the system principal for
+ *   `systemContext`; without one (a test) it is core's fallback principal
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof systemContext>[0]): AddonHost;

package/lib/src/utils/addonHost.js

@@ -10,6 +10,15 @@
  * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
  *   this add-on declares in its own `config/default-config.json`, so one
  *   add-on cannot write records that look like another's or like core's;
+ * - `systemContext(reason)` is bound to the running engine, so the system
+ *   principal's name comes from core (`NGDPBASE_SYSTEM_USER`), never from
+ *   the add-on (#1973);
+ * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
+ *   bound to its slug, so it can never set another add-on's;
+ * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
+ *   are core's own pure functions, handed on unchanged, so an add-on never
+ *   imports them from `dist/` (#1813);
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -18,11 +27,18 @@
 import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
 import { actorOf } from '../context/ActorContext.js';
 import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
+import { resolveEgressPolicy } from '../http/egressPolicy.js';
+import { validateUrl } from '../http/ssrf.js';
+import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
+import { isAtLeast } from './version.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import { auditDeclarationsFrom } from './auditRegistry.js';
 import logger from './logger.js';
+/** A host built outside a site (the test kit, with no setter given) has no account store. */
+const noPersonSwitch = () => Promise.reject(new Error('setEnabledForPerson is not available: this host was built without a site'));
 /**
  * The audit event names one add-on declares: the permission entries carrying
  * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
@@ -45,8 +61,12 @@ function refuseUndeclared(slug, name, declared) {
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - That add-on's own default-config.json, as folded into
  *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ * @param setEnabledForPerson - This add-on's switch setter, slug already bound
+ *   (`AddonsManager` supplies it); without one, the host's setter refuses
+ * @param engine - The running engine, which names the system principal for
+ *   `systemContext`; without one (a test) it is core's fallback principal
  */
-export function buildAddonHost(slug, addonDefaults) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPersonSwitch, engine) {
     const declared = addonDeclaredAuditEvents(addonDefaults);
     const hostAddonAuditEventName = (name) => {
         const checked = addonAuditEventName(name);
@@ -66,7 +86,14 @@ export function buildAddonHost(slug, addonDefaults) {
         actorOf,
         jobContextFromRequest,
         jobContextFromSystem,
+        systemContext: (reason) => systemContext(engine, reason),
         logger: logger.child({ addon: slug }),
-        guardedFetch
+        guardedFetch,
+        setEnabledForPerson,
+        resolveEgressPolicy,
+        validateUrl,
+        createGuardedElasticsearchClient,
+        refusedNodeMessage,
+        isAtLeast
     });
 }

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

@@ -34,8 +34,8 @@ export declare function evaluateSeededAddonPage(args: {
 /**
  * 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).
+ * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`,
+ * #1918).
  *
  *  - `status` — `modified` when the live copy differs from what ships,
  *    `current` when it is the same.

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

@@ -50,6 +50,10 @@ 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";
+    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    readonly CONSENT_GRANT: "consent-grant";
+    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    readonly CONSENT_WITHDRAW: "consent-withdraw";
     /** 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) */
@@ -140,6 +144,22 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_EXTEND: "share-extend";
     /** Share link revoked; pairs with token-revoke */
     readonly SHARE_REVOKE: "share-revoke";
+    /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
+    readonly SIGNINAPPROVAL_ABANDON: "signinapproval-abandon";
+    /** Sign-in approval: the person pressed Approve (#1532) */
+    readonly SIGNINAPPROVAL_APPROVE: "signinapproval-approve";
+    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    readonly SIGNINAPPROVAL_DENY: "signinapproval-deny";
+    /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
+    readonly SIGNINAPPROVAL_EXPIRE: "signinapproval-expire";
+    /** Sign-in approval: the approval page was opened, with the opener's IP and browser; opening changes nothing (#1532) */
+    readonly SIGNINAPPROVAL_OPEN: "signinapproval-open";
+    /** Sign-in approval: an approval message was sent for a waiting sign-in, saying from where (IP, approximate place, browser) (#1532) */
+    readonly SIGNINAPPROVAL_REQUEST: "signinapproval-request";
+    /** Sign-in approval: the approval message could not be sent (transport error, or no channel configured) (#1532) */
+    readonly SIGNINAPPROVAL_SENDFAIL: "signinapproval-sendfail";
+    /** Sign-in approval: another approval message was asked for too soon and not sent (#1532) */
+    readonly SIGNINAPPROVAL_THROTTLE: "signinapproval-throttle";
     /** A user's private store copy created at its door (#1414) — with key material when sealed; never the words or a key in the record */
     readonly STORE_CREATE: "store-create";
     /** A takeout imported into its owner's private store; a bulk write — who, which store, pages and files written or skipped */

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

@@ -57,6 +57,10 @@ 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',
+    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    CONSENT_GRANT: 'consent-grant',
+    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    CONSENT_WITHDRAW: 'consent-withdraw',
     /** 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) */
@@ -147,6 +151,22 @@ export const AUDIT_EVENT = {
     SHARE_EXTEND: 'share-extend',
     /** Share link revoked; pairs with token-revoke */
     SHARE_REVOKE: 'share-revoke',
+    /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
+    SIGNINAPPROVAL_ABANDON: 'signinapproval-abandon',
+    /** Sign-in approval: the person pressed Approve (#1532) */
+    SIGNINAPPROVAL_APPROVE: 'signinapproval-approve',
+    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    SIGNINAPPROVAL_DENY: 'signinapproval-deny',
+    /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
+    SIGNINAPPROVAL_EXPIRE: 'signinapproval-expire',
+    /** Sign-in approval: the approval page was opened, with the opener's IP and browser; opening changes nothing (#1532) */
+    SIGNINAPPROVAL_OPEN: 'signinapproval-open',
+    /** Sign-in approval: an approval message was sent for a waiting sign-in, saying from where (IP, approximate place, browser) (#1532) */
+    SIGNINAPPROVAL_REQUEST: 'signinapproval-request',
+    /** Sign-in approval: the approval message could not be sent (transport error, or no channel configured) (#1532) */
+    SIGNINAPPROVAL_SENDFAIL: 'signinapproval-sendfail',
+    /** Sign-in approval: another approval message was asked for too soon and not sent (#1532) */
+    SIGNINAPPROVAL_THROTTLE: 'signinapproval-throttle',
     /** A user's private store copy created at its door (#1414) — with key material when sealed; never the words or a key in the record */
     STORE_CREATE: 'store-create',
     /** A takeout imported into its owner's private store; a bulk write — who, which store, pages and files written or skipped */

package/lib/src/utils/backupCrypto.js

@@ -0,0 +1,275 @@
+/**
+ * Encrypted backup files (#1561, #1876): the backup document, every file
+ * archive beside it, and the credentials store, under `NGDPBASE_BACKUP_KEY`.
+ * The database files are encrypted by SQLCipher itself (`sqliteBackup.ts`);
+ * everything else a backup writes goes through here.
+ *
+ * Format, version 1:
+ *
+ * - `NGDPBK01` (8 bytes), then a big-endian u32 length and that many bytes of
+ *   JSON header: the cipher, the key derivation (scrypt, its cost and a fresh
+ *   random salt), the backup key's fingerprint (`backupKeyFingerprint`, never
+ *   the key), an 8-byte random nonce prefix and the chunk size.
+ * - Then records: u32 plaintext length, one byte (1 on the last record, else
+ *   0), the ciphertext, and its 16-byte AES-256-GCM tag. Each record's nonce
+ *   is the prefix and its u32 index; its additional data is the SHA-256 of
+ *   the header, the index and the last-record byte. So a record moved,
+ *   dropped, swapped from another file or cut off at the end fails, and so
+ *   does any change to the header.
+ *
+ * Streamed both ways, a chunk at a time: a file's size never becomes memory.
+ * Decrypting checks the fingerprint first, so a backup made under another key
+ * is refused by name ({@link BackupKeyMismatchError}) before any work is done.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from 'node:crypto';
+import { Readable, Transform, Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { backupKeyFingerprint, BACKUP_KEY_ENV } from './backupKey.js';
+import { open } from 'node:fs/promises';
+/** The first bytes of every encrypted backup file. */
+export const BACKUP_FILE_MAGIC = Buffer.from('NGDPBK01', 'ascii');
+/** What an encrypted backup file's name ends with. */
+export const ENCRYPTED_SUFFIX = '.enc';
+/** The key derivation's cost, written into each file's header so a reader uses the file's own. A format constant, not a tunable: changing it changes no file already written. */
+const KDF = { N: 16384, r: 8, p: 1 };
+const CHUNK_BYTES = 64 * 1024;
+const SALT_BYTES = 16;
+const NONCE_PREFIX_BYTES = 8;
+const TAG_BYTES = 16;
+const RECORD_HEAD = 5;
+/** The largest header a reader accepts: a header is a few hundred bytes. */
+const MAX_HEADER = 4096;
+/** A backup file made under a different backup key than the one set now. */
+export class BackupKeyMismatchError extends Error {
+    fileFingerprint;
+    keyFingerprint;
+    constructor(fileFingerprint, keyFingerprint) {
+        super(`it was made with a different backup key (fingerprint ${fileFingerprint}; ${BACKUP_KEY_ENV} now has ${keyFingerprint}). Set ${BACKUP_KEY_ENV} to the key it was made with`);
+        this.fileFingerprint = fileFingerprint;
+        this.keyFingerprint = keyFingerprint;
+        this.name = 'BackupKeyMismatchError';
+    }
+}
+function deriveKey(backupKey, salt, kdf) {
+    const options = { N: kdf.N, r: kdf.r, p: kdf.p, maxmem: 256 * kdf.N * kdf.r };
+    return new Promise((resolve, reject) => scrypt(backupKey, salt, 32, options, (err, key) => (err ? reject(err) : resolve(key))));
+}
+function nonceFor(prefix, index) {
+    const nonce = Buffer.alloc(12);
+    prefix.copy(nonce, 0, 0, 8);
+    nonce.writeUInt32BE(index, 8);
+    return nonce;
+}
+function aadFor(headerHash, index, last) {
+    const tail = Buffer.alloc(5);
+    tail.writeUInt32BE(index, 0);
+    tail.writeUInt8(last ? 1 : 0, 4);
+    return Buffer.concat([headerHash, tail]);
+}
+function requireKey(backupKey) {
+    if (!backupKey.trim())
+        throw new Error(`a backup key is required: ${BACKUP_KEY_ENV} is not set`);
+}
+/** Whether these bytes (a file's first) are an encrypted backup file. */
+export function isEncryptedBackup(head) {
+    return head.length >= BACKUP_FILE_MAGIC.length && head.subarray(0, BACKUP_FILE_MAGIC.length).equals(BACKUP_FILE_MAGIC);
+}
+/** Whether the file on disk is an encrypted backup file, read from its first bytes only. */
+export async function fileIsEncrypted(file) {
+    const handle = await open(file, 'r');
+    try {
+        const head = Buffer.alloc(BACKUP_FILE_MAGIC.length);
+        const { bytesRead } = await handle.read(head, 0, head.length, 0);
+        return isEncryptedBackup(head.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** A stream that encrypts what is written to it under `backupKey`. */
+export function encryptStream(backupKey) {
+    requireKey(backupKey);
+    let key = null;
+    let headerHash;
+    let prefix;
+    let index = 0;
+    let pending = Buffer.alloc(0);
+    const record = (plain, last) => {
+        const cipher = createCipheriv('aes-256-gcm', key, nonceFor(prefix, index));
+        cipher.setAAD(aadFor(headerHash, index, last));
+        const ct = Buffer.concat([cipher.update(plain), cipher.final()]);
+        const head = Buffer.alloc(RECORD_HEAD);
+        head.writeUInt32BE(plain.length, 0);
+        head.writeUInt8(last ? 1 : 0, 4);
+        index++;
+        return Buffer.concat([head, ct, cipher.getAuthTag()]);
+    };
+    const start = async (stream) => {
+        if (key)
+            return;
+        const salt = randomBytes(SALT_BYTES);
+        prefix = randomBytes(NONCE_PREFIX_BYTES);
+        const header = {
+            format: 1,
+            cipher: 'aes-256-gcm',
+            kdf: { alg: 'scrypt', ...KDF, salt: salt.toString('base64') },
+            keyFingerprint: backupKeyFingerprint(backupKey),
+            noncePrefix: prefix.toString('base64'),
+            chunkBytes: CHUNK_BYTES
+        };
+        const json = Buffer.from(JSON.stringify(header), 'utf8');
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(json.length, 0);
+        const headerBytes = Buffer.concat([BACKUP_FILE_MAGIC, len, json]);
+        headerHash = createHash('sha256').update(headerBytes).digest();
+        key = await deriveKey(backupKey, salt, KDF);
+        stream.push(headerBytes);
+    };
+    return new Transform({
+        transform(chunk, _enc, done) {
+            start(this).then(() => {
+                pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+                // The last record is written at the end, so a full chunk is held back
+                // until more follows: the last-record byte is then always right.
+                while (pending.length > CHUNK_BYTES) {
+                    this.push(record(pending.subarray(0, CHUNK_BYTES), false));
+                    pending = pending.subarray(CHUNK_BYTES);
+                }
+                done();
+            }, done);
+        },
+        flush(done) {
+            start(this).then(() => {
+                this.push(record(pending, true));
+                done();
+            }, done);
+        }
+    });
+}
+/**
+ * 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 function decryptStream(backupKey) {
+    requireKey(backupKey);
+    let buffer = Buffer.alloc(0);
+    let header = null;
+    let headerHash;
+    let prefix;
+    let key;
+    let index = 0;
+    let ended = false;
+    const parseHeader = async () => {
+        if (buffer.length < BACKUP_FILE_MAGIC.length + 4)
+            return false;
+        if (!isEncryptedBackup(buffer))
+            throw new Error('not an encrypted backup file');
+        const len = buffer.readUInt32BE(BACKUP_FILE_MAGIC.length);
+        if (len === 0 || len > MAX_HEADER)
+            throw new Error('the encrypted backup file has a damaged header');
+        const total = BACKUP_FILE_MAGIC.length + 4 + len;
+        if (buffer.length < total)
+            return false;
+        const headerBytes = buffer.subarray(0, total);
+        let parsed;
+        try {
+            parsed = JSON.parse(headerBytes.subarray(BACKUP_FILE_MAGIC.length + 4).toString('utf8'));
+        }
+        catch {
+            throw new Error('the encrypted backup file has a damaged header');
+        }
+        // The header is not authenticated until the first record verifies, so
+        // nothing in it may set the cost of the work before that: format 1 has
+        // one key derivation cost, and a header asking for another is refused
+        // (a crafted file must not make the server run a huge scrypt).
+        const salt = typeof parsed.kdf?.salt === 'string' ? Buffer.from(parsed.kdf.salt, 'base64') : Buffer.alloc(0);
+        const noncePrefix = typeof parsed.noncePrefix === 'string' ? Buffer.from(parsed.noncePrefix, 'base64') : Buffer.alloc(0);
+        if (parsed.format !== 1 || parsed.cipher !== 'aes-256-gcm' || parsed.kdf?.alg !== 'scrypt'
+            || parsed.kdf.N !== KDF.N || parsed.kdf.r !== KDF.r || parsed.kdf.p !== KDF.p
+            || salt.length !== SALT_BYTES || noncePrefix.length !== NONCE_PREFIX_BYTES
+            || !(parsed.chunkBytes > 0 && parsed.chunkBytes <= 16 * CHUNK_BYTES)) {
+            throw new Error('the encrypted backup file is in a format this build does not read');
+        }
+        const fingerprint = backupKeyFingerprint(backupKey);
+        if (parsed.keyFingerprint !== fingerprint)
+            throw new BackupKeyMismatchError(String(parsed.keyFingerprint), fingerprint);
+        headerHash = createHash('sha256').update(headerBytes).digest();
+        prefix = noncePrefix;
+        key = await deriveKey(backupKey, salt, KDF);
+        header = parsed;
+        buffer = buffer.subarray(total);
+        return true;
+    };
+    const drain = (stream) => {
+        while (buffer.length >= RECORD_HEAD) {
+            if (ended)
+                throw new Error('the encrypted backup file has bytes after its last record');
+            const len = buffer.readUInt32BE(0);
+            const last = buffer.readUInt8(4);
+            if (len > header.chunkBytes || last > 1)
+                throw new Error('the encrypted backup file is damaged');
+            const size = RECORD_HEAD + len + TAG_BYTES;
+            if (buffer.length < size)
+                return;
+            const decipher = createDecipheriv('aes-256-gcm', key, nonceFor(prefix, index));
+            decipher.setAAD(aadFor(headerHash, index, last === 1));
+            decipher.setAuthTag(buffer.subarray(RECORD_HEAD + len, size));
+            let plain;
+            try {
+                plain = Buffer.concat([decipher.update(buffer.subarray(RECORD_HEAD, RECORD_HEAD + len)), decipher.final()]);
+            }
+            catch {
+                throw new Error('the encrypted backup file does not verify: it is damaged or was changed');
+            }
+            index++;
+            buffer = buffer.subarray(size);
+            if (last === 1)
+                ended = true;
+            if (plain.length > 0)
+                stream.push(plain);
+        }
+    };
+    return new Transform({
+        transform(chunk, _enc, done) {
+            buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+            (header ? Promise.resolve(true) : parseHeader()).then((ready) => {
+                if (ready)
+                    drain(this);
+                done();
+            }).catch(done);
+        },
+        flush(done) {
+            try {
+                if (!header)
+                    throw new Error(buffer.length === 0 ? 'the encrypted backup file is empty' : 'the encrypted backup file has a damaged header');
+                drain(this);
+                if (!ended || buffer.length > 0)
+                    throw new Error('the encrypted backup file is cut short');
+                done();
+            }
+            catch (err) {
+                done(err);
+            }
+        }
+    });
+}
+async function collect(source, transform) {
+    const out = [];
+    await pipeline(Readable.from([source]), transform, new Writable({
+        write(chunk, _enc, done) {
+            out.push(chunk);
+            done();
+        }
+    }));
+    return Buffer.concat(out);
+}
+/** Encrypt a whole buffer (the backup document, already in memory). */
+export function encryptBuffer(data, backupKey) {
+    return collect(data, encryptStream(backupKey));
+}
+/** Decrypt a whole buffer. */
+export function decryptBuffer(data, backupKey) {
+    return collect(data, decryptStream(backupKey));
+}

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

@@ -0,0 +1,36 @@
+/** A backup document's shape: what every backup holds at its top level. */
+export interface BackupDocument {
+    version: string;
+    timestamp: string;
+    application: string;
+    managers: Record<string, unknown>;
+}
+/** Throws, naming what is missing, when `doc` is not a backup document. */
+export declare function validateBackupDocument(doc: BackupDocument): void;
+/**
+ * The document in `bytes`, read as a restore reads it: an encrypted one only
+ * under `backupKey`, gzip by its first bytes whatever the name says.
+ *
+ * @param name - the file's name, for the messages
+ * @param options.validate - check the shape (default true)
+ */
+export declare function readBackupDocument(bytes: Buffer, backupKey: string, name: string, options?: {
+    validate?: boolean;
+}): Promise<BackupDocument>;
+/** What a read-back found: the document's timestamp and how many manager parts it holds. */
+export interface VerifiedBackup {
+    timestamp: string;
+    managers: number;
+}
+/** The worker's job: the document's bytes, the key and the name. */
+export interface VerifyJob {
+    bytes: Uint8Array;
+    backupKey: string;
+    name: string;
+}
+/**
+ * Read a backup document back on a worker thread (#1563): rejects, naming
+ * why, when it does not decrypt (a wrong key, a changed byte, a bad tag), does
+ * not decompress, does not parse, or is not a backup document.
+ */
+export declare function verifyBackupOffThread(bytes: Buffer, backupKey: string, name: string, timeoutMs: number): Promise<VerifiedBackup>;

package/lib/src/utils/backupDocument.js

@@ -0,0 +1,99 @@
+/**
+ * Reading a backup document back (#1563): decrypt it under the backup key
+ * (the GCM tag of every record is checked), decompress it, parse it, and
+ * check its shape. The one place a document is read: a restore reads it this
+ * way, and every backup is read back this way before it counts as one.
+ *
+ * `verifyBackupOffThread` does it on a worker thread, so a large document is
+ * never decrypted, unzipped and parsed on the thread that serves requests.
+ */
+import { promisify } from 'node:util';
+import zlib from 'node:zlib';
+import { Worker } from 'node:worker_threads';
+import { decryptBuffer, isEncryptedBackup } from './backupCrypto.js';
+import { BACKUP_KEY_ENV } from './backupKey.js';
+const gunzip = promisify(zlib.gunzip);
+/** Throws, naming what is missing, when `doc` is not a backup document. */
+export function validateBackupDocument(doc) {
+    if (!doc || typeof doc !== 'object')
+        throw new Error('Invalid backup: not a backup document');
+    if (!doc.version)
+        throw new Error('Invalid backup: missing version');
+    if (!doc.timestamp)
+        throw new Error('Invalid backup: missing timestamp');
+    if (!doc.managers || typeof doc.managers !== 'object')
+        throw new Error('Invalid backup: missing or invalid managers data');
+}
+/**
+ * The document in `bytes`, read as a restore reads it: an encrypted one only
+ * under `backupKey`, gzip by its first bytes whatever the name says.
+ *
+ * @param name - the file's name, for the messages
+ * @param options.validate - check the shape (default true)
+ */
+export async function readBackupDocument(bytes, backupKey, name, options = {}) {
+    let plain = bytes;
+    if (isEncryptedBackup(bytes)) {
+        if (!backupKey)
+            throw new Error(`The backup ${name} is encrypted under the backup key, and ${BACKUP_KEY_ENV} is not set`);
+        try {
+            plain = await decryptBuffer(bytes, backupKey);
+        }
+        catch (err) {
+            throw new Error(`The backup ${name} could not be read: ${err.message}`, { cause: err });
+        }
+    }
+    let json;
+    if (plain[0] === 0x1f && plain[1] === 0x8b) {
+        try {
+            json = (await gunzip(plain)).toString('utf8');
+        }
+        catch (err) {
+            throw new Error(`The backup ${name} does not decompress: ${err.message}`, { cause: err });
+        }
+    }
+    else {
+        json = plain.toString('utf8');
+    }
+    let doc;
+    try {
+        doc = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`The backup ${name} is not a readable document: ${err.message}`, { cause: err });
+    }
+    if (options.validate !== false)
+        validateBackupDocument(doc);
+    return doc;
+}
+/**
+ * Read a backup document back on a worker thread (#1563): rejects, naming
+ * why, when it does not decrypt (a wrong key, a changed byte, a bad tag), does
+ * not decompress, does not parse, or is not a backup document.
+ */
+export function verifyBackupOffThread(bytes, backupKey, name, timeoutMs) {
+    // Compiled, the worker is the .js beside this file. From source (vitest, tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './backupVerifyWorker.ts' : './backupVerifyWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const workerData = { bytes, backupKey, name };
+        const worker = new Worker(entry, { workerData, ...(fromSource ? { execArgv: ['--import', 'tsx'] } : {}) });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`reading the backup ${name} back did not finish within ${timeoutMs} ms (ngdpbase.backup.verify-timeout-ms)`)));
+            void worker.terminate();
+        }, timeoutMs);
+        worker.once('message', (m) => {
+            settle(() => (m.ok ? resolve(m.result) : reject(new Error(m.error))));
+        });
+        worker.once('error', (err) => settle(() => reject(err)));
+        worker.once('exit', (code) => settle(() => reject(new Error(`the backup read-back worker exited (code ${code}) without a result`))));
+    });
+}