@jwilleke/ngdpbase-types 5.22.0 → 5.24.0

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

@@ -56,6 +56,10 @@ export interface GuardedFetchOptions {
     maxRedirects?: number;
     maxBytes?: number;
     timeoutMs?: number;
+    /**
+     * Request headers. Without a `User-Agent` (any case), the configured default
+     * is added (#1947, ./userAgent.ts).
+     */
     headers?: Record<string, string>;
     method?: 'GET' | 'HEAD' | 'POST';
     /**

package/lib/src/http/guardedFetch.js

@@ -27,6 +27,7 @@ import { Agent as HttpAgent, request as httpRequest } from 'node:http';
 import { Agent as HttpsAgent, request as httpsRequest } from 'node:https';
 import { validateUrl } from './ssrf.js';
 import { guardedLookup } from './guardedLookup.js';
+import { defaultUserAgent } from './userAgent.js';
 const DEFAULTS = { maxRedirects: 5, maxBytes: 8 * 1024 * 1024, timeoutMs: 30_000 };
 /** Statuses that carry a `Location` worth following. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -57,6 +58,16 @@ async function readCapped(body, maxBytes) {
     }
     return Buffer.concat(parts);
 }
+/** The caller's headers, plus the default User-Agent when they name none (#1947). */
+function withDefaultUserAgent(headers) {
+    const out = { ...headers };
+    if (Object.keys(out).some((name) => name.toLowerCase() === 'user-agent'))
+        return out;
+    const userAgent = defaultUserAgent();
+    if (userAgent)
+        out['User-Agent'] = userAgent;
+    return out;
+}
 /** The first header value, since node presents repeated headers as an array. */
 function headerValue(value) {
     return Array.isArray(value) ? value[0] : value;
@@ -74,6 +85,7 @@ export async function guardedFetch(target, options) {
     const timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
     const transport = options.transport ?? nodeTransport;
     const body = options.body === undefined ? undefined : Buffer.from(options.body);
+    const headers = withDefaultUserAgent(options.headers);
     // keepAlive: false is load-bearing. A pooled connection skips resolution on
     // reuse, so the guard would run for the first request to a host and never
     // again — every later request riding a connection validated once, long ago.
@@ -90,7 +102,7 @@ export async function guardedFetch(target, options) {
         chain.push(url.toString());
         const res = await transport(url, {
             method: options.method ?? 'GET',
-            headers: body ? { ...options.headers, 'Content-Length': String(body.length) } : (options.headers ?? {}),
+            headers: body ? { ...headers, 'Content-Length': String(body.length) } : headers,
             agent: url.protocol === 'https:' ? agents.https : agents.http,
             timeoutMs,
             ...(body ? { body } : {})

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

@@ -0,0 +1,36 @@
+/**
+ * The default `User-Agent` of outbound requests (#1947).
+ *
+ * Node's `http.request` adds no User-Agent, so before this every request from
+ * `guardedFetch` went out without one, and APIs that require one refused it
+ * (api.weather.gov answers 403). A caller that names its own User-Agent keeps
+ * it; every other request gets the one built here.
+ *
+ * The value is configuration, `ngdpbase.http.user-agent`, a template read on
+ * every request so an operator's change applies without a restart:
+ *
+ * - `{version}` is `ngdpbase.version`;
+ * - `{base-url}` is `ngdpbase.application.base-url`, only when it was set
+ *   explicitly. When it was not, the localhost default would be a wrong
+ *   contact, so a parenthesised part holding `{base-url}` is left out,
+ *   brackets and all (`ngdpbase/5.23.0 (+{base-url})` → `ngdpbase/5.23.0`);
+ * - an empty template sends no default User-Agent.
+ *
+ * `guardedFetch` has no engine to read configuration from, so the engine hands
+ * it the source at boot (`setUserAgentSource`), the way the log-redaction table
+ * is filled. Until then, and in tests that set none, no default is added.
+ */
+export declare const USER_AGENT_KEY = "ngdpbase.http.user-agent";
+/** What reading the template needs from `ConfigurationManager`. */
+export interface UserAgentConfig {
+    getProperty(key: string, fallback?: unknown): unknown;
+    isBaseUrlExplicit?(): boolean;
+}
+/** Fill a template. `baseUrl` null leaves out the part that names it. */
+export declare function renderUserAgent(template: string, version: string, baseUrl: string | null): string;
+/** The User-Agent the configuration asks for, '' for none. */
+export declare function userAgentFromConfig(config: UserAgentConfig): string;
+/** Set at boot by the engine; `null` clears it (tests). */
+export declare function setUserAgentSource(next: (() => string) | null): void;
+/** The default User-Agent now, '' when none is configured. */
+export declare function defaultUserAgent(): string;

package/lib/src/http/userAgent.js

@@ -0,0 +1,53 @@
+/**
+ * The default `User-Agent` of outbound requests (#1947).
+ *
+ * Node's `http.request` adds no User-Agent, so before this every request from
+ * `guardedFetch` went out without one, and APIs that require one refused it
+ * (api.weather.gov answers 403). A caller that names its own User-Agent keeps
+ * it; every other request gets the one built here.
+ *
+ * The value is configuration, `ngdpbase.http.user-agent`, a template read on
+ * every request so an operator's change applies without a restart:
+ *
+ * - `{version}` is `ngdpbase.version`;
+ * - `{base-url}` is `ngdpbase.application.base-url`, only when it was set
+ *   explicitly. When it was not, the localhost default would be a wrong
+ *   contact, so a parenthesised part holding `{base-url}` is left out,
+ *   brackets and all (`ngdpbase/5.23.0 (+{base-url})` → `ngdpbase/5.23.0`);
+ * - an empty template sends no default User-Agent.
+ *
+ * `guardedFetch` has no engine to read configuration from, so the engine hands
+ * it the source at boot (`setUserAgentSource`), the way the log-redaction table
+ * is filled. Until then, and in tests that set none, no default is added.
+ */
+export const USER_AGENT_KEY = 'ngdpbase.http.user-agent';
+/** Fill a template. `baseUrl` null leaves out the part that names it. */
+export function renderUserAgent(template, version, baseUrl) {
+    let out = template.split('{version}').join(version);
+    out = baseUrl
+        ? out.split('{base-url}').join(baseUrl)
+        : out.replace(/\s*\([^()]*\{base-url\}[^()]*\)/g, '').split('{base-url}').join('');
+    return out.trim();
+}
+/** The User-Agent the configuration asks for, '' for none. */
+export function userAgentFromConfig(config) {
+    const template = config.getProperty(USER_AGENT_KEY, '');
+    if (typeof template !== 'string' || template.trim() === '')
+        return '';
+    const text = (key) => {
+        const value = config.getProperty(key, '');
+        return typeof value === 'string' ? value : '';
+    };
+    const version = text('ngdpbase.version');
+    const baseUrl = config.isBaseUrlExplicit?.() ? text('ngdpbase.application.base-url').replace(/\/+$/, '') : '';
+    return renderUserAgent(template, version, baseUrl || null);
+}
+let source = null;
+/** Set at boot by the engine; `null` clears it (tests). */
+export function setUserAgentSource(next) {
+    source = next;
+}
+/** The default User-Agent now, '' when none is configured. */
+export function defaultUserAgent() {
+    return source ? source() : '';
+}

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

@@ -620,7 +620,9 @@ declare class AuthManager extends BaseManager {
      * Disable and delete both come through here, from UserManager, so nothing
      * an account holds is left reachable by one path and not the other.
      *
-     * - Both: every session of the account ends.
+     * - Both: every session of the account ends, destroyed in the live session
+     *   store (#1937); a session the store could not reach is still refused on
+     *   its next request (`checkSessionAccount`).
      * - Disable: its agent tokens, app grants and shares are suspended by the
      *   live owner-is-active checks that refuse them, and its credentials stay,
      *   so turning the account back on restores them.
@@ -1039,7 +1041,8 @@ declare class AuthManager extends BaseManager {
     /**
      * Stamp the session with the account's password-change generation (#1482):
      * at every sign-in, and on the session that changed the password, so that
-     * one stays signed in while every other session of the account ends.
+     * one stays signed in while every other session of the account ends. Also
+     * binds the session to the account itself (`accountCreatedAt`, #1937).
      */
     stampSessionGeneration(req: Request, username: string): Promise<void>;
     /**

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

@@ -319,6 +319,14 @@ declare class BackgroundJobManager extends BaseManager {
     private startDrain;
     /** Every scheduled job, its state and its recent history. */
     listScheduledJobs(): Promise<ScheduledJobView[]>;
+    /**
+     * One scheduled job as `listScheduledJobs` shows it, without its run
+     * history, or null when no job of that id is scheduled. For a manager that
+     * shows its own job's next run (BackupManager, #1563) without reading every
+     * job's history.
+     */
+    scheduledJobView(jobId: string): Promise<ScheduledJobView | null>;
+    private viewOf;
     private scheduledOrThrow;
     /** Refused while the job runs, waits for a retry, or the server is stopping: one run of a job at a time. */
     private assertIdle;

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

@@ -114,6 +114,20 @@ export interface ManagerRestoreOptions {
  * nobody reads, and then the real warning is missed with it.
  */
 export type ManagerState = 'ready' | 'degraded' | 'disabled' | 'failed';
+/**
+ * What a `degraded` or `failed` state means for the person reading it (#1946).
+ *
+ * - `outage`    — the feature is NOT working: what it provides is not happening
+ * - `attention` — the feature works, but an administrator has something to do:
+ *   save the backup key off the server, fix a mistyped value that is read as
+ *   false, move vault files in. Telling them their backups are "silently doing
+ *   nothing" while backups run is a false alarm, and false alarms teach people
+ *   to skip the real one.
+ *
+ * Declared where the state is set (`markDegraded` versus `markNeedsAttention`),
+ * never inferred from the reason's wording.
+ */
+export type DegradedKind = 'outage' | 'attention';
 /**
  * What a manager holds, in one shape (#1006).
  *
@@ -147,6 +161,8 @@ export interface ManagerStatus {
     reason?: string;
     /** The config key at fault, when there is one, so the admin UI can link to it. */
     configKey?: string;
+    /** Whether the feature is down or works but needs an admin (#1946). Present when degraded or failed. */
+    kind?: DegradedKind;
 }
 declare abstract class BaseManager {
     /** Reference to the wiki engine */
@@ -262,6 +278,13 @@ declare abstract class BaseManager {
      *   the signal is buried in its own noise.
      */
     protected markDegraded(reason: string, configKey?: string): boolean;
+    /**
+     * Record that this manager works, but an administrator has something to do
+     * (#1946). Still `degraded` — it stays on the dashboard, is audited, and
+     * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
+     * as down.
+     */
+    protected markNeedsAttention(reason: string, configKey?: string): boolean;
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     protected markDisabled(reason: string): boolean;
     /** Record that this manager could not initialise at all (#1155). */

package/lib/src/managers/BaseManager.js

@@ -162,7 +162,16 @@ class BaseManager {
      *   the signal is buried in its own noise.
      */
     markDegraded(reason, configKey) {
-        return this.transition({ state: 'degraded', reason, configKey });
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'outage' });
+    }
+    /**
+     * Record that this manager works, but an administrator has something to do
+     * (#1946). Still `degraded` — it stays on the dashboard, is audited, and
+     * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
+     * as down.
+     */
+    markNeedsAttention(reason, configKey) {
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'attention' });
     }
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     markDisabled(reason) {
@@ -170,7 +179,7 @@ class BaseManager {
     }
     /** Record that this manager could not initialise at all (#1155). */
     markFailed(reason, configKey) {
-        return this.transition({ state: 'failed', reason, configKey });
+        return this.transition({ state: 'failed', reason, configKey, kind: 'outage' });
     }
     /**
      * Record that this manager is working.
@@ -205,7 +214,7 @@ class BaseManager {
      * PROVABLE.
      */
     transition(next) {
-        const changed = this.status.state !== next.state || this.status.reason !== next.reason;
+        const changed = this.status.state !== next.state || this.status.reason !== next.reason || this.status.kind !== next.kind;
         this.status = next;
         if (!changed)
             return false;

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

@@ -30,6 +30,16 @@ export default class CommentManager extends BaseManager {
      * clear.
      */
     private place;
+    /**
+     * Whether comments are on for `page` (#1951): the page's `comments:` flag,
+     * else its system-category's, else on (`pageNotesAllowed`). The view asks
+     * this before it shows the Comments tab or the plugin's list, and every
+     * write here asks it first. When off, the page's comments are kept and
+     * hidden. `metadata` saves a read when the caller already holds it.
+     */
+    isAllowedOn(page: PageRef, ctx: ActorContext, metadata?: Record<string, unknown> | null): Promise<boolean>;
+    /** Throws {@link PageNotesTurnedOffError} when comments are off for `page` (#1951). */
+    private refuseWhenOff;
     private commentFile;
     /**
      * A page's comments, read as `ctx` may (#1839). Whether `ctx` may read the

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

@@ -216,6 +216,8 @@ declare class DatabaseManager extends BaseManager {
     /** Degrade for one cause; the dashboard shows every cause still standing. */
     private fault;
     private clearFault;
+    /** Every cause still standing; down when any one of them is (#1946). */
+    private markFaults;
     private notify;
     /** Whether every open database passes SQLite's quick check; true when none is configured, false when the configured one could not be opened (#1892). */
     integrityOk(): boolean;

package/lib/src/managers/DatabaseManager.js

@@ -164,7 +164,8 @@ class DatabaseManager extends BaseManager {
         const keyProblem = this.backupKeyProblem();
         if (keyProblem) {
             logger.error(`[DatabaseManager] ${keyProblem}`);
-            this.fault('backup-key', keyProblem);
+            // No key: no database is backed up (down). The database key reused: still backed up (attention, #1946).
+            this.fault('backup-key', keyProblem, this.backupKey() ? 'attention' : 'outage');
         }
     }
     /** Whether an application database is open. */
@@ -346,7 +347,7 @@ class DatabaseManager extends BaseManager {
         const backupKey = this.backupKey();
         if (!backupKey) {
             const reason = `${LEFT_OUT_FOR_NO_KEY}no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
-            this.fault('backup-key', reason);
+            this.fault('backup-key', reason, 'outage');
             throw new Error(reason);
         }
         const key = process.env[DATABASE_KEY_ENV] ?? '';
@@ -354,7 +355,7 @@ class DatabaseManager extends BaseManager {
         if (keyProblem) {
             // D3: still backed up, but as loudly as a missing key.
             logger.error(`[DatabaseManager] ${keyProblem}`);
-            this.fault('backup-key', keyProblem);
+            this.fault('backup-key', keyProblem, 'attention');
             await this.notify('error', 'The backup key is the database key', `${keyProblem}. This backup was still taken.`);
         }
         else {
@@ -642,7 +643,8 @@ class DatabaseManager extends BaseManager {
         if (outcome.refused) {
             const reason = `A staged database restore was NOT applied: ${outcome.refused}. The site started on its current databases (#1723)`;
             logger.error(`[DatabaseManager] ${reason}`);
-            this.fault('restore', reason);
+            // The site runs on its current databases; an admin decides about the restore (#1946).
+            this.fault('restore', reason, 'attention');
             return;
         }
         this.restoredNow = outcome.applied.map((a) => a.name);
@@ -677,9 +679,9 @@ class DatabaseManager extends BaseManager {
         return configured;
     }
     /** Degrade for one cause; the dashboard shows every cause still standing. */
-    fault(cause, reason) {
-        this.faults.set(cause, reason);
-        this.markDegraded([...this.faults.values()].join('; '));
+    fault(cause, reason, kind) {
+        this.faults.set(cause, { reason, kind });
+        this.markFaults();
     }
     clearFault(cause) {
         if (!this.faults.delete(cause))
@@ -687,7 +689,16 @@ class DatabaseManager extends BaseManager {
         if (this.faults.size === 0)
             this.markReady();
         else
-            this.markDegraded([...this.faults.values()].join('; '));
+            this.markFaults();
+    }
+    /** Every cause still standing; down when any one of them is (#1946). */
+    markFaults() {
+        const faults = [...this.faults.values()];
+        const reason = faults.map((f) => f.reason).join('; ');
+        if (faults.some((f) => f.kind === 'outage'))
+            this.markDegraded(reason);
+        else
+            this.markNeedsAttention(reason);
     }
     async notify(level, title, message) {
         try {

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

@@ -37,6 +37,19 @@ export default class FootnoteManager extends BaseManager {
      * the clear.
      */
     private place;
+    /**
+     * Whether footnotes are on for `page` (#1951): the page's `footnotes:` flag,
+     * else its system-category's, else on (`pageNotesAllowed`). Each page is
+     * asked about itself, so one page's flag never reaches another's. The view
+     * asks this before it shows the Footnotes tab, and every write here asks it
+     * first. When off, the page's footnotes are kept and stay readable where
+     * the page's own content lists them (`[{FootnotesPlugin}]`), without the
+     * add, edit and delete controls. `metadata` saves a read when the caller
+     * already holds it.
+     */
+    isAllowedOn(page: PageRef, ctx: ActorContext, metadata?: Record<string, unknown> | null): Promise<boolean>;
+    /** Throws {@link PageNotesTurnedOffError} when footnotes are off for `page` (#1951). */
+    private refuseWhenOff;
     private readMap;
     private writeMap;
     /**

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

@@ -1273,6 +1273,22 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * @param action  - Legacy verb (`view`, `edit`) or policy action; default `view`
      */
     listPagesFor(subject: PermissionSubject | null | undefined, action?: string): Promise<string[]>;
+    /**
+     * Which of these named pages may `subject` perform `action` on — the
+     * {@link listPagesFor} door for a list someone else found: search hits
+     * (#1962), whatever index they came from.
+     *
+     * Each name is resolved as `/view/<name>` resolves it, and the batch is
+     * decided by `PolicyInformationPoint.filterAccessiblePages`, so a hit is
+     * kept exactly when its reader may open the page. A name that resolves to
+     * no page (a ghost in the index) is dropped. Order is preserved; no log line
+     * or audit record per page. Without a PolicyInformationPoint nothing is kept.
+     *
+     * @param subject - The reader's own context, forwarded
+     * @param names   - Page names, as the index holds them
+     * @param action  - Legacy verb (`view`, `edit`) or policy action; default `view`
+     */
+    filterPagesFor(subject: ActorContext | PermissionSubject | null | undefined, names: readonly string[], action?: string): Promise<string[]>;
     /**
      * Get all page titles (explicit alias for getAllPages)
      * Prefer this for new code that only needs page names.

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

@@ -186,6 +186,28 @@ declare class SearchManager extends BaseManager {
      * console.log(`Found ${results.length} pages`);
      */
     searchWithContext(wikiContext: WikiContext, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * How many hits a search returns when its caller does not say:
+     * `ngdpbase.search.maxresults`.
+     */
+    private resultLimit;
+    /**
+     * The provider's hits that this reader may open, up to `wanted` (#1962).
+     *
+     * The search index knows nothing of a page's audience, its `access` rules
+     * or the policies, so every hit is decided by the page-list door
+     * (`PageManager.filterPagesFor` → `PolicyInformationPoint.filterAccessiblePages`),
+     * the same decision `/view` makes, in one batch per round. The decision is
+     * made BEFORE the limit: the provider is asked for `wanted`, and asked again
+     * for twice as many while hidden hits leave the page short and the index
+     * may hold more, so a result count, a total and a page number never count a
+     * page the reader cannot open. `ngdpbase.search.access-filter.max-candidates`
+     * bounds how many hits one search may decide; at the bound the result is
+     * short rather than the site slow.
+     *
+     * Without the door nothing is returned — never the unfiltered index.
+     */
+    private hitsVisibleTo;
     /**
      * Public results, plus the requester's own private pages (#1458).
      *

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

@@ -0,0 +1,94 @@
+/**
+ * SessionStatsManager — in-process reads of the session store (#1246).
+ *
+ * Two things want to know how many sessions exist and who holds them: the
+ * `/api/session-count` and `/api/session-users` routes, and SessionsPlugin,
+ * which renders those numbers into a page. The plugin used to get them by
+ * making an HTTP request to this server's own address through a bare global
+ * `fetch` — an outbound call outside `src/http/` (#1133) that `guardedFetch`
+ * cannot take, because loopback is refused unconditionally (#1186), and one
+ * that silently rendered `0` in any container whose configured host was not
+ * reachable from inside the process.
+ *
+ * The store is an in-process object. Nothing about reading it needs a socket.
+ * app.ts attaches the store it built for express-session; the routes keep
+ * reading `req.sessionStore` (the same object) and both go through the same
+ * two helpers, so there is exactly one implementation of "count sessions" and
+ * "list session users".
+ */
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/** The two optional store methods express-session stores may implement. */
+export interface SessionStoreLike {
+    length?(callback: (err: unknown, count?: number) => void): void;
+    all?(callback: (err: unknown, sessions?: unknown) => void): void;
+    /** session-file-store: the session file names, not the sessions. */
+    list?(callback: (err: unknown, files?: string[]) => void): void;
+    get?(sid: string, callback: (err: unknown, session?: unknown) => void): void;
+    destroy?(sid: string, callback: (err: unknown) => void): void;
+    /** session-file-store keeps its file extension here (default `.json`). */
+    options?: {
+        fileExtension?: string;
+    };
+}
+export interface SessionCount {
+    sessionCount: number;
+    distinctUsers: number;
+}
+export interface SessionUsers {
+    users: string[];
+    anonymous: number;
+    total: number;
+}
+/** Thrown when the store implements neither `length` nor `all`. */
+export declare class SessionStoreUnsupportedError extends Error {
+    constructor(what: string);
+}
+/**
+ * Session count and distinct-user count. Prefers `length` (cheap), falls back
+ * to `all`. Under `length` the distinct-user figure equals the session count,
+ * which is what the route always reported on that path.
+ */
+export declare function countSessions(store: SessionStoreLike): Promise<SessionCount>;
+/**
+ * Authenticated usernames (sorted, distinct) and the anonymous session count.
+ * Needs `all`; under `length` alone the list is empty and every session is
+ * reported as anonymous.
+ */
+export declare function listSessionUsers(store: SessionStoreLike): Promise<SessionUsers>;
+/** A session in the store, with its id. */
+export interface StoredSession {
+    sid: string;
+    session: Record<string, unknown>;
+}
+/**
+ * Every session in the store with its id (#1937): `all()` keyed by id where
+ * the store has it, else list and read each (the file store). A store whose
+ * `all()` returns a bare array gives no ids, so it cannot be listed this way.
+ */
+export declare function storedSessions(store: SessionStoreLike): Promise<StoredSession[]>;
+/**
+ * The private-store handles held by sessions still in the store (#1626).
+ * Uses `all()` where the store has it, else lists and reads each session:
+ * the file store has no `all()`, so the sweep failed on every run there and
+ * no orphaned key was ever dropped.
+ */
+export declare function liveSessionHandles(store: SessionStoreLike): Promise<Set<string>>;
+declare class SessionStatsManager extends BaseManager {
+    private store;
+    constructor(engine: WikiEngine);
+    /** app.ts hands over the store it built for express-session. */
+    attachStore(store: SessionStoreLike): void;
+    hasStore(): boolean;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot count. */
+    count(): Promise<SessionCount>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    users(): Promise<SessionUsers>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    liveHandles(): Promise<Set<string>>;
+    /** Every session in the store with its id (#1937). @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list by id. */
+    sessions(): Promise<StoredSession[]>;
+    /** Remove one session from the store (#1937). @throws Error when no store is attached, or SessionStoreUnsupportedError when it cannot destroy. */
+    destroy(sid: string): Promise<void>;
+}
+export default SessionStatsManager;

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

@@ -488,7 +488,27 @@ declare class UserManager extends BaseManager {
     createSession(username: string, additionalData?: Record<string, unknown>): Promise<string>;
     getSession(sessionId: string): Promise<UserSession | null>;
     deleteSession(sessionId: string): Promise<void>;
-    deleteUserSessions(username: string): Promise<void>;
+    /**
+     * End every signed-in session of `username` in the live session store
+     * (#1937): the account was deleted or turned off (`AuthManager.closeAccess`).
+     * Each goes through `endSession` (its keys dropped, `authentication-logout`
+     * recorded with the reason) and is removed from the store. Returns how many.
+     * The provider's own session list was cleared here before; nothing writes it,
+     * and the store express-session reads was never touched.
+     */
+    deleteUserSessions(username: string, reason: 'account-deleted' | 'account-disabled', from?: {
+        ipAddress?: string;
+    }): Promise<number>;
+    /**
+     * End every signed-in session in the store that no longer belongs to its
+     * account (#1937): the account is gone, turned off, another account of the
+     * same name, or its password changed since (`checkSessionAccount`, the
+     * per-request rule). Run once at startup, so sessions left from before the
+     * fix, or from a close the store missed, do not wait for their next request.
+     */
+    endStaleSessions(): Promise<number>;
+    /** End and remove each signed-in session `which` names a reason for; none without a session store. */
+    private endStoredSessions;
     backup(): Promise<BackupData>;
     restore(backupData: BackupData): Promise<void>;
 }

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

@@ -76,6 +76,10 @@ export interface CategoryConfig {
     source?: CategorySource;
     enabled?: boolean;
     key?: string;
+    /** `false`: its pages show no Comments tab and take no comment, unless a page says otherwise (#1951). */
+    comments?: boolean;
+    /** `false`: its pages show no Footnotes tab and take no footnote change, unless a page says otherwise (#1951). */
+    footnotes?: boolean;
 }
 /**
  * System categories configuration map

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

@@ -148,6 +148,10 @@ declare class LunrSearchProvider extends BaseSearchProvider {
      * owner's private container: it is found only by its owner — no role, and no
      * frontmatter audience, reaches in (docs/private-stores.md, Access;
      * the same rule PolicyInformationPoint applies at Tier 0).
+     *
+     * This only narrows; it is not the access decision. Audience, `access`
+     * rules and the policies are not here: SearchManager puts every hit through
+     * the page-list door before it reaches anyone (#1962).
      */
     private isDocVisible;
     /**

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

@@ -5,6 +5,19 @@ import type { Request } from 'express';
 import type { PageFrontmatter } from '../types/Page.js';
 import { type ShareGrant } from '../types/Share.js';
 import type { MediaItem } from '../providers/BaseMediaProvider.js';
+/**
+ * The system principal's name from configuration, or a refusal (#631, #1953).
+ *
+ * `ngdpbase.system.principal` ships as the bare env-ref `$NGDPBASE_SYSTEM_USER`,
+ * which throws when the variable is unset; an empty value is refused the same
+ * way. One rule for both readers: the PIP at run time, and `WikiEngine` right
+ * after configuration loads, before any manager writes — so a first boot
+ * without a principal refuses before the admin account exists, not after it
+ * was written without its person (#1953).
+ */
+export declare function systemPrincipalFromConfig(configManager: {
+    getProperty(key: string, defaultValue: unknown): unknown;
+} | null | undefined): string;
 /**
  * Minimal WikiContext interface for type safety
  * TODO: Convert WikiContext.js to TypeScript and import proper type

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

@@ -30,6 +30,8 @@ declare module 'express-session' {
         privateStoreHandle?: string;
         /** The account's password-change generation when this session signed in (#1482). */
         sessionGeneration?: number;
+        /** The `createdAt` of the account this session signed in to (#1937): a later account of the same name is not it. */
+        accountCreatedAt?: string;
         /** How this session signed in: provider, factors with their times, amr / aal / acr (#1523). */
         signIn?: SignInRecord;
         /** A pending WebAuthn challenge (#448): single-use, tied to its purpose, short-lived. */

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

@@ -39,6 +39,8 @@ export declare function archiveReadKey(manager: string, data: {
 export declare function backupDirectoryPart(manager: string, part: string, folder: string | null, options?: ManagerBackupOptions, extra?: {
     exclude?: (relative: string) => boolean;
 }): Promise<BackupData>;
+/** The log's note of entries deleted while they were backed up (#1563): skipped, not a failure. */
+export declare function vanishedNote(vanished: string[]): string;
 /**
  * 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.

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

@@ -61,6 +61,28 @@ export declare function pageNotesPath(page: PageRef, roots: PageNotesRoots): Pag
 export declare function pageNotesPlace(ctx: ActorContext, page: PageRef, roots: PageNotesRoots): Promise<PageNotesPath & {
     io: StoreFileIO;
 }>;
+/**
+ * Whether `kind` is on for a page (#1951, docs/system-category.md): THE rule,
+ * said once. The page's own frontmatter (`comments:` / `footnotes:`) wins;
+ * without it, its system-category entry's field of the same name decides;
+ * unset is on. Only a boolean counts, and only `false` turns it off.
+ *
+ * Pure. {@link pageNotesAllowed} gathers the page's metadata and entry for it.
+ */
+export declare function pageNotesOn(kind: PageNotesKind, pageMetadata: Record<string, unknown> | null | undefined, categoryEntry: Record<string, unknown> | null | undefined): boolean;
+/**
+ * {@link pageNotesOn} for `page`, as `ctx` reads it (#1951): its metadata
+ * (`metadata` when the caller already holds it, else the stored page's) and
+ * its system-category entry, the default system-category's when the page
+ * names none. A page not stored yet has no metadata, so its system-category
+ * decides. The managers' `isAllowedOn` doors are this; nothing else calls it.
+ */
+export declare function pageNotesAllowed(engine: EngineLike, kind: PageNotesKind, page: PageRef, ctx: ActorContext, metadata?: Record<string, unknown> | null): Promise<boolean>;
+/** A footnote or comment write refused because that kind is turned off for the page (#1951). Routes answer it with 403. */
+export declare class PageNotesTurnedOffError extends Error {
+    readonly kind: PageNotesKind;
+    constructor(kind: PageNotesKind);
+}
 /**
  * Move a page's notes when the page changes place — into a vault, out of one,
  * or between two — through both sides' I/O, as its history moves: sealed going
@@ -115,8 +137,8 @@ export declare function isVaultPageUuid(pagesDirectory: string, layout: PrivateS
 }, uuid: string): Promise<boolean>;
 /** The manager state a startup check sets and clears: the manager's own (BaseManager). */
 export interface CheckStateHooks {
-    /** True when this is a new state. */
-    markDegraded(reason: string): boolean;
+    /** True when this is a new state. The pages work; an admin moves the notes in, so it needs attention, not down (#1946). */
+    markNeedsAttention(reason: string): boolean;
     /** Clears the degraded state only while it is still `reason`, so another fault stays reported. */
     markReadyIfDegradedBy(reason: string): boolean;
 }

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

@@ -0,0 +1,9 @@
+/**
+ * Where an operator reads about the settings a boot refuses without (#1953).
+ *
+ * SETUP.md's "Required settings" section lists each one with why; `.env.example`
+ * is the full list of variables. Every refusal for a missing or wrong required
+ * setting ends with this line, so the operator who hits one learns about the
+ * others in the same read instead of one boot at a time.
+ */
+export declare const REQUIRED_SETTINGS_HELP = "See \"Required settings\" in SETUP.md: https://github.com/jwilleke/ngdpbase/blob/master/SETUP.md#required-settings";

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

@@ -0,0 +1,26 @@
+export type AccountEndReason = 'account-deleted' | 'account-disabled' | 'password-changed';
+interface AccountLike {
+    createdAt?: unknown;
+    isActive?: boolean;
+    sessionGeneration?: number;
+}
+interface SessionLike {
+    accountCreatedAt?: unknown;
+    signedInAt?: unknown;
+    sessionGeneration?: unknown;
+}
+/** The value a session is bound to: the account's creation time, or '' for a record without one. */
+export declare function accountBindingOf(account: AccountLike | null | undefined): string;
+/**
+ * What one request (or the sweep) does to a signed-in session, given its
+ * account as stored now (null when there is none). `bind` is set on a session
+ * signed in before the binding existed that still belongs to its account: the
+ * caller writes it to `accountCreatedAt`, once.
+ */
+export declare function checkSessionAccount(stored: SessionLike | Record<string, unknown>, account: AccountLike | null | undefined): {
+    end: AccountEndReason;
+} | {
+    end: null;
+    bind?: string;
+};
+export {};

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

@@ -1,4 +1,4 @@
-export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded';
+export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded' | 'account-deleted' | 'account-disabled';
 export declare function endSession(engine: {
     getManager(name: string): unknown;
 }, session: {

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

@@ -9,10 +9,11 @@ export declare const SYSTEM_CATEGORY_KEY = "ngdpbase.system-category";
 /**
  * The fields of an entry that are its `owner`'s declaration (operator,
  * 2026-09-29): `encrypt` and `defaultPrivate` stand, and `shareMaxDays` is
- * decided by the owner. For an entry an add-on declares, a site's
+ * decided by the owner; `comments` and `footnotes` stand too (operator,
+ * 2026-10-21, #1951). For an entry an add-on declares, a site's
  * `app-custom-config.json` never changes them, nor `owner` itself.
  */
-export declare const OWNER_DECIDED_FIELDS: readonly ["owner", "encrypt", "defaultPrivate", "shareMaxDays"];
+export declare const OWNER_DECIDED_FIELDS: readonly ["owner", "encrypt", "defaultPrivate", "shareMaxDays", "comments", "footnotes"];
 /** One mistyped value: what is wrong, and what every reader takes it to mean. */
 export interface SystemCategoryValueProblem {
     /** Names the entry, the field and the bad value. */
@@ -23,8 +24,11 @@ export interface SystemCategoryValueProblem {
 /**
  * What is wrong with the types of one entry's values, one per field, naming
  * the entry and the field. Empty when sound. `defaultPrivate` is the boolean
- * `true` or `false`, or the string `"choice"`; `encrypt` is a boolean.
- * Anything else is compared as false by every reader, so the string `"true"`
- * would start pages public and leave the vault unsealed.
+ * `true` or `false`, or the string `"choice"`; `encrypt`, `comments` and
+ * `footnotes` are booleans.
+ * Any other `defaultPrivate` or `encrypt` is compared as false by every
+ * reader, so the string `"true"` would start pages public and leave the vault
+ * unsealed. Any other `comments` or `footnotes` is read as on, since only
+ * `false` turns a tab off.
  */
 export declare function systemCategoryValueProblems(key: string, entry: unknown): SystemCategoryValueProblem[];

package/lib/src/utils/systemCategoryRules.js

@@ -9,16 +9,20 @@ export const SYSTEM_CATEGORY_KEY = 'ngdpbase.system-category';
 /**
  * The fields of an entry that are its `owner`'s declaration (operator,
  * 2026-09-29): `encrypt` and `defaultPrivate` stand, and `shareMaxDays` is
- * decided by the owner. For an entry an add-on declares, a site's
+ * decided by the owner; `comments` and `footnotes` stand too (operator,
+ * 2026-10-21, #1951). For an entry an add-on declares, a site's
  * `app-custom-config.json` never changes them, nor `owner` itself.
  */
-export const OWNER_DECIDED_FIELDS = ['owner', 'encrypt', 'defaultPrivate', 'shareMaxDays'];
+export const OWNER_DECIDED_FIELDS = ['owner', 'encrypt', 'defaultPrivate', 'shareMaxDays', 'comments', 'footnotes'];
 /**
  * What is wrong with the types of one entry's values, one per field, naming
  * the entry and the field. Empty when sound. `defaultPrivate` is the boolean
- * `true` or `false`, or the string `"choice"`; `encrypt` is a boolean.
- * Anything else is compared as false by every reader, so the string `"true"`
- * would start pages public and leave the vault unsealed.
+ * `true` or `false`, or the string `"choice"`; `encrypt`, `comments` and
+ * `footnotes` are booleans.
+ * Any other `defaultPrivate` or `encrypt` is compared as false by every
+ * reader, so the string `"true"` would start pages public and leave the vault
+ * unsealed. Any other `comments` or `footnotes` is read as on, since only
+ * `false` turns a tab off.
  */
 export function systemCategoryValueProblems(key, entry) {
     if (!entry || typeof entry !== 'object')
@@ -37,5 +41,14 @@ export function systemCategoryValueProblems(key, entry) {
             readAs: 'it is read as false, so the vault is not sealed'
         });
     }
+    // #1951: only the boolean false turns a page's Comments or Footnotes tab off.
+    for (const kind of ['comments', 'footnotes']) {
+        if (e[kind] !== undefined && typeof e[kind] !== 'boolean') {
+            problems.push({
+                message: `system-category '${key}': ${kind} must be true or false, got ${JSON.stringify(e[kind])}`,
+                readAs: `it is read as true, so its pages keep the ${kind === 'comments' ? 'Comments' : 'Footnotes'} tab`
+            });
+        }
+    }
     return problems;
 }

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

@@ -5,17 +5,35 @@ export interface TreeArchiveOutcome {
     bytes: number;
     /** Entries left out because they are not a file or a folder (a symbolic link), relative to the root. */
     skipped: string[];
+    /** Entries that were there when the folder was listed and were deleted before they were read (#1563), relative to the root. */
+    vanished: string[];
 }
 /**
- * Write `entries` (paths relative to `root`; default: everything in it) into
- * `target`, streamed. `exclude` leaves out a path relative to `root`, in
- * posix form. A missing `root` writes an empty archive. Never overwrites.
+ * Whether a backup's read failed because the entry it was reading was
+ * deleted meanwhile (#1563): a page, a version folder or a file removed
+ * while the backup walked past it. That entry is skipped and counted, never
+ * a failed backup — the site keeps running while it is backed up (#1213).
+ * Every other error (EACCES, EIO, …) is a real failure and still fails.
  */
-export declare function writeTreeArchive(target: string, root: string, options?: {
+export declare function vanishedDuringBackup(err: unknown): boolean;
+type TreeArchiveOptions = {
     entries?: string[];
     exclude?: (relative: string) => boolean;
     backupKey?: string;
-}): Promise<TreeArchiveOutcome>;
+};
+/**
+ * Write `entries` (paths relative to `root`; default: everything in it) into
+ * `target`, streamed. `exclude` leaves out a path relative to `root`, in
+ * posix form. A missing `root` writes an empty archive. Never overwrites.
+ *
+ * An entry deleted while the archive is written (#1563) — the tar stream
+ * stops at the first file it can no longer find — is not a failure: the
+ * archive is written again from a fresh listing, without it, and the entry
+ * is named in `vanished`. It is written again only while each attempt finds
+ * another entry gone, so it ends once the deleting stops; the same entry
+ * missing twice, or one still there, is a real failure.
+ */
+export declare function writeTreeArchive(target: string, root: string, options?: TreeArchiveOptions): Promise<TreeArchiveOutcome>;
 /**
  * Extract `archive` into `dest`, which is emptied first, streamed.
  * `select(relative)` picks the entries to extract (default: all). Refuses —
@@ -42,3 +60,4 @@ export declare function listTreeArchive(archive: string, onEntry: (entry: {
 }): Promise<void>;
 /** The first `n` bytes of a file, read without reading the rest. */
 export declare function readHead(file: string, n: number): Promise<Buffer>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.22.0",
+  "version": "5.24.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -46,7 +46,7 @@
     "ipaddr.js": "^2.5.0",
     "jose": "^6.2.12",
     "linkedom": "^0.18.13",
-    "markdown-it": "^14.3.1",
+    "markdown-it": "^14.3.3",
     "minimatch": "^10.2.6",
     "minisearch": "7.2.0",
     "multer": "^2.4.0",