@jwilleke/ngdpbase-types 5.25.0 → 5.26.0

package/README.md

@@ -11,7 +11,7 @@ import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-type
 import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
 ```
 
-- The main entry is types only. Importing it at run time fails, on purpose.
+- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
 - `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

package/lib/packages/ngdpbase-types/index.d.ts

@@ -30,6 +30,10 @@ export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
 export type { default as ExportManager } from '../../src/managers/ExportManager.js';
 export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';
+export type { default as PageManager } from '../../src/managers/PageManager.js';
+export type { PageAction } from '../../src/utils/pageUrl.js';
+export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
+export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';

package/lib/src/http/egressPolicy.js

@@ -0,0 +1,61 @@
+/**
+ * Configuration to policy (#1133).
+ *
+ * The operator sets two CIDR lists; this turns them into the `EgressPolicy`
+ * the guard enforces, and reconciles them at BOOT so a contradiction is a
+ * startup message rather than one dropped image months later — which would
+ * surface as a `fetch` warning indistinguishable from the remote host being
+ * down.
+ *
+ * Contradictions resolve by FIREWALL CONVENTION and none of them stops the
+ * boot (#1144, D8). #1133 chose longest-prefix match — the routing rule,
+ * because the values are routes — so a general overlap is not a conflict at
+ * all. The cases longest prefix cannot decide are settled here: an allow entry
+ * reaching the mechanism is unsatisfiable and dropped, and a range in both
+ * lists is a prefix-length tie the DENY wins.
+ *
+ * `ngdpbase.security.profile` used to decide whether a contradiction stopped
+ * the boot. That was the profile looking for a job: `iptables` rejects a bad
+ * rule and keeps the chain, and the Kubernetes API server rejects an invalid
+ * NetworkPolicy while the others keep applying. Neither takes the workload
+ * down. The one case with no safe silent resolution — a malformed range, where
+ * dropping a DENY fails open — is reported separately for #1152.
+ */
+import { reconcilePolicy } from './ssrf.js';
+export const DENIED_RANGES_KEY = 'ngdpbase.security.egress.denied-ranges';
+export const ALLOWED_RANGES_KEY = 'ngdpbase.security.egress.allowed-ranges';
+/** Only strings can be CIDRs; anything else in the list is discarded, not coerced. */
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * Read the configured ranges, reconcile them, and report what could not be
+ * resolved.
+ *
+ * A contradiction never widens access. Where the two lists disagree the
+ * stricter reading wins, which is the only direction a security control should
+ * fail when nobody can be asked.
+ */
+export function resolveEgressPolicy(read) {
+    const deniedRanges = stringList(read(DENIED_RANGES_KEY, []));
+    const allowedRanges = stringList(read(ALLOWED_RANGES_KEY, []));
+    const { conflicts, malformed, duplicates } = reconcilePolicy(deniedRanges, allowedRanges);
+    const unusable = new Set(malformed);
+    // An allow entry is dropped when it cannot be parsed, when it reaches the
+    // mechanism, or when the same range is also denied. The last is D8's tie
+    // break: equal prefix lengths give longest-prefix nothing to work with, so
+    // the deny wins.
+    const safeAllowed = allowedRanges.filter((range) => !unusable.has(range)
+        && !duplicates.includes(range)
+        && !conflicts.some((c) => c.startsWith('allowed-ranges:') && c.includes(`'${range}'`)));
+    // A denied range is dropped ONLY when it cannot be parsed. Previously a
+    // range appearing in both lists was removed from here too, so the operator's
+    // stricter statement was discarded along with the looser one and the range
+    // fell back to the built-in defaults.
+    const safeDenied = deniedRanges.filter((range) => !unusable.has(range));
+    return {
+        policy: { deniedRanges: safeDenied, allowedRanges: safeAllowed },
+        conflicts,
+        malformed
+    };
+}

package/lib/src/http/guardedElasticsearch.d.ts

@@ -0,0 +1,27 @@
+import { Client, type ClientOptions } from '@elastic/elasticsearch';
+import { type Resolver } from './guardedLookup.js';
+import { type ConfigReader } from './egressPolicy.js';
+import { type EgressPolicy } from './ssrf.js';
+export interface GuardedElasticsearchOptions {
+    /** Per-request timeout in ms; the SDK's default when omitted. */
+    requestTimeout?: number;
+    /**
+     * The resolution step, for tests only — the same single seam `guardedLookup`
+     * exposes. Production leaves it unset and `node:dns` answers.
+     */
+    resolver?: Resolver;
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export declare function guardedClientOptions(node: string, policy: EgressPolicy, options?: GuardedElasticsearchOptions): ClientOptions;
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export declare function createGuardedElasticsearchClient(node: string, read: ConfigReader, options?: GuardedElasticsearchOptions): Client;
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export declare function refusedNodeMessage(who: string, node: string, reason: string): string;

package/lib/src/http/guardedElasticsearch.js

@@ -0,0 +1,99 @@
+/**
+ * The Elasticsearch client, built inside the boundary (#1188).
+ *
+ * `@elastic/elasticsearch` opens sockets the same way `fetch` does, and until
+ * #1188 it did so from two places outside `src/http/` — the search provider
+ * and the elasticsearch addon — with `new Client({ node })` and no policy at
+ * all. The boundary check (#1139) could not see it because the SDK was not in
+ * its list of client modules, so the guard read green while the process
+ * connected to whatever `es-url` said, loopback and RFC1918 included.
+ *
+ * This is the only place the SDK is constructed. It hands the client Node's
+ * `http` connection class with agents whose `lookup` is the guarded one, so
+ * every socket the client opens — the first request, a retry, a sniffed node —
+ * is judged against the instance's egress policy at connect time, exactly as
+ * `guardedFetch` does. There is no ungated constructor to reach for: the
+ * scanner now names the SDK, so an `import { Client }` outside this directory
+ * fails `lint:http`.
+ *
+ * What this means for an operator: an Elasticsearch node on `localhost` is
+ * refused — loopback is mechanism, not policy (#1186), and no allow entry
+ * opens it. A node on the LAN needs its prefix in
+ * `ngdpbase.security.egress.allowed-ranges`, the same as sist2. Both call
+ * sites say so at boot when the configured address would be refused.
+ */
+import { Agent as HttpAgent } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { isIP } from 'node:net';
+import { Client, HttpConnection } from '@elastic/elasticsearch';
+import { ESSRF_BLOCKED, guardedLookup } from './guardedLookup.js';
+import { resolveEgressPolicy } from './egressPolicy.js';
+import { isAddressAllowed, REFUSAL } from './ssrf.js';
+/**
+ * The connect step, guarding the case the lookup never sees.
+ *
+ * Node calls an agent's `lookup` only for a NAME. A URL whose host is an IP
+ * literal — `http://192.168.0.10:9200`, `http://127.0.0.1:9200` — goes
+ * straight to the socket, so a guard that lives only in `lookup` waves every
+ * literal address through. Found by pointing the first version of this at
+ * jimstest's LAN node under an empty policy and watching `ping` return true.
+ * `guardedFetch` covers the same hole with `validateUrl` before each hop;
+ * here the judgement sits in `createConnection`, which every socket passes
+ * through, literal or resolved.
+ */
+function guardedCreateConnection(policy, connect) {
+    return function guarded(options, callback) {
+        const host = String(options.host ?? options.hostname ?? 'localhost');
+        if (isIP(host) && !isAddressAllowed(host, policy)) {
+            const err = Object.assign(new Error(`${REFUSAL}: ${host}`), { code: ESSRF_BLOCKED });
+            if (callback) {
+                process.nextTick(callback, err);
+                return undefined;
+            }
+            throw err;
+        }
+        // Node's own connect for this agent — `net.createConnection` for http,
+        // the TLS one for https. The agent has merged its options in, so `lookup`
+        // (the guarded one) rides along for a host that is a name.
+        return connect.call(this, options, callback);
+    };
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export function guardedClientOptions(node, policy, options = {}) {
+    // keepAlive stays on, as the SDK's own default agent has it: a kept socket
+    // was judged when it was opened, and both guards run again for every new one.
+    const lookup = guardedLookup(policy, options.resolver);
+    const agents = { http: new HttpAgent({ lookup, keepAlive: true }), https: new HttpsAgent({ lookup, keepAlive: true }) };
+    // `createConnection` is a method of the agent, not an option it accepts:
+    // Node reads `this.createConnection` when it opens a socket. Replaced on the
+    // instance, wrapping the prototype's own so TLS setup stays Node's.
+    const method = (agent) => Object.getPrototypeOf(agent).createConnection;
+    agents.http.createConnection =
+        guardedCreateConnection(policy, method(agents.http));
+    agents.https.createConnection =
+        guardedCreateConnection(policy, method(agents.https));
+    return {
+        node,
+        ...(options.requestTimeout !== undefined ? { requestTimeout: options.requestTimeout } : {}),
+        Connection: HttpConnection,
+        agent: (connection) => (connection.url.protocol === 'https:' ? agents.https : agents.http)
+    };
+}
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export function createGuardedElasticsearchClient(node, read, options = {}) {
+    return new Client(guardedClientOptions(node, resolveEgressPolicy(read).policy, options));
+}
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export function refusedNodeMessage(who, node, reason) {
+    return (`[${who}] Elasticsearch node ${node} is refused by the egress policy (${reason}). ` +
+        'Loopback and link-local can never be opened; a LAN address needs its prefix in ' +
+        'ngdpbase.security.egress.allowed-ranges. Every request to it will fail. (#1188)');
+}

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

@@ -11,12 +11,14 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/158}
  */
 import { type ActorContext } from '../context/ActorContext.js';
+import type { BackupFolder } from './BaseManager.js';
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { User } from '../types/User.js';
 import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
 import { type AddonHost } from '../utils/addonHost.js';
+import { ConsentRequiredError } from '../types/Consent.js';
 /**
  * Type passed to `AddonModule.profileSection()` (#534). Matches what
  * `UserManager.getUser()` returns at runtime — `User` minus the password
@@ -76,6 +78,14 @@ export interface AddonModule {
      * frozen. An add-on that takes two arguments keeps working until it moves.
      */
     register(engine: WikiEngine, config: Record<string, unknown>, host?: AddonHost): Promise<void> | void;
+    /**
+     * Folders it keeps data in besides its `dataPath` (#1985), given its
+     * configuration. Its `dataPath` is backed up and restored without being
+     * declared; an add-on declares only further folders, and writes no backup
+     * code. BackupManager archives each one, stages it in a site restore, and
+     * puts it in place before `register()` runs at the next start.
+     */
+    backupFolders?(config: Record<string, unknown>): BackupFolder[];
     /**
      * Optional health check returning add-on status details.
      */
@@ -464,6 +474,20 @@ declare class AddonsManager extends BaseManager {
      * not registered yet says nothing about whether it still provides it.
      */
     addonsLoaded(): boolean;
+    /**
+     * An add-on's folders (#1985): its `dataPath` — `ngdpbase.addons.<slug>.dataPath`,
+     * or `<FAST_STORAGE>/<slug>` when that is not set, as the bundled add-ons
+     * read it — under the part name of its slug, then any further folders its
+     * module declares. A `dataPath` that is the instance data folder, or holds
+     * it, is never one: a restore would swap the whole site's data.
+     */
+    private addonFolders;
+    /** Each loaded add-on's `dataPath` and declared folders (#1985), in load order: what BackupManager backs up for it. */
+    addonBackupFolders(): Array<{
+        slug: string;
+        dataPath: string | null;
+        folders: BackupFolder[];
+    }>;
     /**
      * Get add-on specific configuration
      */
@@ -671,14 +695,26 @@ declare class AddonsManager extends BaseManager {
      *
      * Errors are caught per-addon and logged so one bad addon cannot block
      * other addons' saves or the core-preferences save.
+     *
+     * #1603: an add-on whose switch was refused because its documents are not
+     * accepted yet (`ConsentRequiredError`) is returned, so the route can tell
+     * the person what to accept instead of the save failing silently.
      */
-    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<void>;
+    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<{
+        consentRequired: ConsentRequiredError[];
+    }>;
     /**
      * The add-ons the site's listings show (#1965): enabled, and not
      * `listed: false` in their manifest, in load order. Cheap: it calls no
      * add-on's status(), so a page can render it.
      */
     listedAddons(): AddonListing[];
+    /**
+     * Whether `slug` is an add-on whose manifest says `perPerson: true` (#1963),
+     * loaded or still loading. ConsentManager asks it when an add-on registers
+     * documents: they guard the per-person switch, so only such an add-on has any.
+     */
+    isPerPerson(slug: string): boolean;
     /** #1963: the loaded add-ons whose manifest says `perPerson: true`, in load order. */
     private perPersonAddons;
     /**

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

@@ -1,6 +1,5 @@
-import BaseManager, { BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import BaseManager, { BackupData, type BackupArchiveTarget, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats, type SiteRestoreStaging, type StagedRestoreAtStart } from './BaseManager.js';
 import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from '../providers/attachmentFilesBackup.js';
-import type { PartOutcome } from '../utils/siteRestore.js';
 import { type ActorContext } from '../context/ActorContext.js';
 /**
  * Marks an error as "the audit record could not be written", not "the action
@@ -36,11 +35,11 @@ interface BaseAttachmentProvider {
     backup(): Promise<unknown>;
     restore(backupData: unknown): Promise<void>;
     /** #1876: the files themselves beside the backup document, and their staged restore. */
-    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
-    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+    backupFiles?(archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, siteRestore: SiteRestoreStaging): Promise<{
         skippedVaults: string[];
     }>;
-    takeRestoreAtStart?(): PartOutcome | null;
+    takeRestoreAtStart?(): StagedRestoreAtStart | null;
     shutdown(): Promise<void>;
     getProviderInfo(): {
         features: string[];

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

@@ -30,7 +30,7 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
  */
 import BaseManager from './BaseManager.js';
-import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
+import type { BackupData, BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
@@ -107,6 +107,12 @@ export declare function credentialLabel(label: unknown): string;
  */
 export interface PendingSignIn {
     handle: string;
+    /**
+     * The id every audit record of this sign-in's approval carries (#1532), so
+     * the steps read as one trail. Random and separate from the handle and the
+     * link token, which are secrets.
+     */
+    id: string;
     username: string;
     first: AuthenticateResult;
     /** The requesting browser's binding value (an HTTP-only cookie); every step must present it. */
@@ -115,15 +121,54 @@ export interface PendingSignIn {
     expiresAt: number;
     requestIp?: string;
     requestUserAgent?: string;
+    /** Roughly where the request came from ("Columbus, United States"), or null when no source says (#1532). */
+    requestLocation?: string | null;
     /** Private-store keys unlocked by the password, held until the sign-in completes or is dropped. */
     privateStoreHandle?: string;
     /** The second factor, once satisfied. */
     approved?: SatisfiedFactor;
-    /** Refused by the person ("this wasn't me"). */
+    /** Refused by the person (Deny). */
     denied?: boolean;
     /** When the last approval message went out, for the resend limit. */
     lastSentAt?: number;
 }
+/**
+ * What an approval request says about a waiting sign-in (#1532): one source
+ * for the message and the page.
+ */
+export interface ApprovalAbout {
+    /** The site's name (`ngdpbase.application-name`). */
+    site: string;
+    /** When it was asked, in the account holder's own time zone. */
+    when: string;
+    /** "Chrome on Windows", or null when the browser could not be named. */
+    device: string | null;
+    /** The IP address it came from (Express's `req.ip`, so `trust-proxy` applies). */
+    ip?: string;
+    /** Roughly where ("Columbus, United States"), or null when no source says. */
+    location: string | null;
+}
+/** What the approval page shows about a waiting sign-in (#1532). */
+export interface ApprovalDetails extends ApprovalAbout {
+    username: string;
+    requestedAt: number;
+    userAgent?: string;
+    /** The sentence the message says, as HTML with every value escaped. */
+    sentenceHtml: string;
+}
+/**
+ * The approval sentence (#1532, decided wording plus the IP and place):
+ * "A sign-in request for Willeke Family was sent at 2 Oct 2026, 14:02 EDT
+ * from Chrome on Windows at IP address 81.2.69.160, near Columbus, United
+ * States." `strong` marks the site and time, `text` every other value; for
+ * HTML both escape.
+ */
+export declare function approvalSentence(about: ApprovalAbout, strong?: (v: string) => string, text?: (v: string) => string): string;
+/** Who opened the approval page or pressed its button (#1532): recorded, never trusted for anything. */
+export interface ApprovalVisitor {
+    ip?: string;
+    userAgent?: string;
+}
 /** A second factor a person has enrolled and can use now. */
 export interface AvailableSecondFactor {
     id: 'email-link';
@@ -202,6 +247,18 @@ export type OutsideSignIn =
 /** The state was already used: no second session. */
  | {
     outcome: 'replayed';
+}
+/**
+ * #1532: the provider's sign-in reached only AAL1 and the account has a
+ * second factor: held as a pending sign-in, as after a password. The route
+ * binds the browser (`binding`), keeps `handle` in the session and sends the
+ * person to the second-factor page; `next` is where they were going.
+ */
+ | {
+    outcome: 'second-step';
+    handle: string;
+    binding: string;
+    next: string;
 };
 /** What the one completion step leaves for the route (#1743): where to go instead, when a pending identity waits to be confirmed. */
 export interface SignInCompleted {
@@ -1030,6 +1087,12 @@ declare class AuthManager extends BaseManager {
         privateStoreHandle?: string;
         returnTo?: string;
     }): Promise<SignInCompleted>;
+    /**
+     * Whether `username` has core documents to accept (#1603), asked of
+     * ConsentManager. A store that cannot be read asks nothing, loudly: a
+     * broken consent folder must not lock everyone out.
+     */
+    private termsPendingFor;
     /**
      * Start the signed-in session's lifetime (#1767), on the new session after
      * regeneration: `signedInAt`, from which `ngdpbase.session.max-age` caps it
@@ -1117,32 +1180,79 @@ declare class AuthManager extends BaseManager {
      * is not offered. Empty means the sign-in is one step, as before.
      */
     secondFactorsFor(username: string): AvailableSecondFactor[];
+    /**
+     * Whether a successful first step needs a second (#1532, operator
+     * 2026-10-22): everyone who arrives with only a password behind them — a
+     * password typed here, or an outside provider's sign-in at AAL1 — when the
+     * account has a second factor it can use now. Never after an email link
+     * (the second factor would go to the same inbox), and never after a sign-in
+     * already at AAL2 or above (a passkey, a provider whose second factor the
+     * admin trusts).
+     */
+    needsSecondStep(result: AuthenticateResult): boolean;
+    /**
+     * Roughly where `req` came from, for the approval message (#1532):
+     * Cloudflare's location headers when `ngdpbase.server.behind-cloudflare`,
+     * else the GeoLite2 City file at `ngdpbase.server.geolite2-city-file`, else
+     * null. Read when asked, so a change applies at the next sign-in. The IP is
+     * Express's `req.ip`, which honours `ngdpbase.server.trust-proxy`.
+     */
+    approximateLocation(req: Pick<Request, 'ip'> & {
+        get?: (name: string) => string | undefined;
+    }): Promise<string | null>;
     /** Hold a sign-in whose first factor passed, until a second factor completes it. Returns its handle. */
     beginTwoStep(first: AuthenticateResult, ctx: {
         binding: string;
         ip?: string;
         userAgent?: string;
+        location?: string | null;
         privateStoreHandle?: string;
     }): Promise<string>;
     /** The pending sign-in, for the browser that started it; null when gone, expired, or another browser. */
     pendingSignIn(handle: string | undefined, binding: string | undefined): PendingSignIn | null;
+    /**
+     * Record one step of a sign-in's approval (#1532): every record carries the
+     * pending sign-in's `id` (never its handle or the link token), the account
+     * it is for, and who took the step — the IP and browser of the request, the
+     * opener or the presser. `user` is the account signing in: there is no
+     * session yet, so no proxy (whom to act for is chosen after sign-in).
+     */
+    private recordApproval;
+    /**
+     * HTML escaping for the approval message and page (#1532): PluginManager's
+     * formatter (#1820), the one escapeHtml. Its absence is a wiring fault, not
+     * a reason to send a value unescaped.
+     */
+    private escapeHtml;
+    /** Where the sign-in asked from, as the request, send and expiry records say it. */
+    private static askedFrom;
     /**
      * Email a one-time approval link for the pending sign-in (#1523, #1532).
      * The link only opens the approval page; the button there approves, so a
      * mail scanner opening links approves nothing. Limited to one per minute.
+     * Each outcome is recorded: sent (`signinapproval-request`), too soon
+     * (`-throttle`), or not sent (`-sendfail`).
      */
     sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable' | 'failed'>;
-    /** What the approval page shows about the waiting sign-in; null for an unknown or used link. */
-    approvalDetails(token: string): {
-        username: string;
-        requestedAt: number;
-        ip?: string;
-        userAgent?: string;
-    } | null;
+    /**
+     * What the approval page shows about the waiting sign-in; null for an
+     * unknown or used link. Opening the page changes nothing, but it is
+     * recorded (`signinapproval-open`) with who opened it (#1532): a mail
+     * scanner opens links too.
+     */
+    approvalDetails(token: string, opener?: ApprovalVisitor): Promise<ApprovalDetails | null>;
+    /**
+     * What an approval request says about a waiting sign-in (#1532), one source
+     * for the message and the page: the site's name, when it was asked in the
+     * account holder's own time zone (their preference, else the site default),
+     * the browser and device it came from (null when the header names
+     * neither), its IP address, and roughly where (null when no source says).
+     */
+    private approvalContext;
     /** Approve the waiting sign-in from its link (the button press). Single use; returns the username, or null. */
-    approveByToken(token: string): string | null;
-    /** Refuse the waiting sign-in from its link ("this wasn't me"). Returns the username, or null. */
-    denyByToken(token: string): string | null;
+    approveByToken(token: string, presser?: ApprovalVisitor): Promise<string | null>;
+    /** Refuse the waiting sign-in from its link (Deny). Returns the username, or null. */
+    denyByToken(token: string, presser?: ApprovalVisitor): Promise<string | null>;
     /**
      * The finished sign-in, once its second factor is satisfied — both factors,
      * assessed together. Single use: the pending entry is gone after this.
@@ -1151,8 +1261,15 @@ declare class AuthManager extends BaseManager {
         result: AuthenticateResult;
         privateStoreHandle?: string;
     } | null;
+    /**
+     * The waiting browser gave up the sign-in (Cancel, #1532): dropped, its
+     * keys locked, and recorded as `signinapproval-abandon`.
+     */
+    abandonTwoStep(handle: string, binding: string, from?: ApprovalVisitor): Promise<void>;
     /** Drop a pending sign-in and lock any keys it held. */
     dropPending(handle: string): void;
+    /** A pending sign-in past its time: dropped, and recorded once as `signinapproval-expire` (#1532). */
+    private expirePending;
     private sweepPending;
     /**
      * Start enrolling the account's email address as a second factor (#1523).
@@ -1265,25 +1382,26 @@ declare class AuthManager extends BaseManager {
     isEnabled(providerId: string): boolean;
     /** Returns all registered providers (for admin UI). */
     getProviders(): AuthProvider[];
-    /**
-     * The provider list, and the credentials store (#1876): passkeys, TOTP,
-     * verified email and phone, devices, linked identities and proxy grants,
-     * as its own file beside the document, __always encrypted under
-     * `NGDPBASE_BACKUP_KEY`__ (`<stem>.credentials.tar.enc`). Without the key the
-     * store is left out and the backup is reported incomplete; it is never in a
-     * backup unencrypted. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`,
-     * which is not in the backup: a site restored under another credentials key
-     * holds them in quarantine (#1633).
-     */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /**
-     * Stage the credentials store from a backup for the next start, with the
-     * rest of a site restore (#1876). A backup that left it out (no backup key
-     * when it was taken) stages nothing: the store on the site stays, and the
-     * restore's notification names it as not restored.
-     */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
-    /** Staged for the next start with the rest of a site restore (#1876). */
-    restoreIsStaged(): boolean;
+    /** `ngdpbase.auth.credentials.file`, resolved: the credentials store. */
+    private configuredCredentialsFile;
+    /**
+     * The provider list. The credentials store (#1876) — passkeys, TOTP,
+     * verified email and phone, devices, linked identities and proxy grants —
+     * is a declared file (`backupFolders`), which BackupManager writes beside
+     * the document as `data.credentials`.
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * The credentials store, as its own file beside the backup document,
+     * __always encrypted under `NGDPBASE_BACKUP_KEY`__
+     * (`<stem>.credentials.tar.enc`; #1876, declared since #1985). Without the
+     * key it is left out and the backup is reported incomplete; it is never in
+     * a backup unencrypted. A backup that left it out stages nothing: the store
+     * on the site stays, and the restore's notification names it as not
+     * restored. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`, which is
+     * not in the backup: a site restored under another credentials key holds
+     * them in quarantine (#1633).
+     */
+    backupFolders(): BackupFolder[];
 }
 export default AuthManager;

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

@@ -1,4 +1,4 @@
-import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
+import BaseManager, { type BackupData, type BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { type JobContext } from '../context/JobContext.js';
 import { type ScheduleInput } from '../utils/schedule.js';
@@ -432,21 +432,31 @@ declare class BackgroundJobManager extends BaseManager {
      */
     private settleAfterRestore;
     /**
-     * Job state in a backup (#1876). Files (`ngdpbase.jobs.state.dir`): the
-     * state, run history and checkpoints as `<stem>.jobs.tar` beside the
-     * document, without the slot locks, which belong to the server that holds
-     * them. In the database: nothing here — it is in the database backup.
+     * Where job state is kept in files, before this manager has started
+     * (#1985): null when it is in the database, held for an unavailable
+     * database, or a test's own provider. After the start, `stateDir`.
      */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /** File job state is staged for the next start with the rest of a site restore (#1876). Database job state comes back with the database. */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    private configuredFileStateDir;
+    /**
+     * File job state (`ngdpbase.jobs.state.dir`) is a declared folder (#1876,
+     * #1985): the state, run history and checkpoints as `<stem>.jobs.tar`
+     * beside the document, without the slot locks, which belong to the server
+     * that holds them. A backup without it (its job state was in the database)
+     * stages nothing for it. Job state in the database is in the database
+     * backup, and comes back with it.
+     */
+    backupFolders(): BackupFolder[];
+    /** Where job state is when it is not a declared folder: the database, or nowhere while held (#1876). */
+    backup(): Promise<BackupData>;
+    /** Database job state comes back with the database; file job state is a declared folder BackupManager stages (#1876, #1985). */
     restoreIsStaged(): boolean;
     /**
-     * Put staged file job state in place, at start, before it is opened
-     * (#1876). The runs in the live state since the backup was taken are read
-     * first, before it is replaced, for the restore's notification.
+     * Whether file job state was put back from a backup at this start (#1876):
+     * BaseManager applied it before this manager opened it (#1985). The runs
+     * in the state it replaced, started since the backup, are read from where
+     * it was kept, for the restore's notification.
      */
-    private applyRestoreAtStart;
+    private noteRestoreAtStart;
     /**
      * The job runs the live application database held, since the backup, when
      * this start's restore replaced it (#1876): read from the copy DatabaseManager