@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

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

@@ -77,6 +77,23 @@ export interface ScheduledJobView {
     /** History, newest first. A run with no slot was started by hand. */
     runs: JobRunRecord[];
 }
+/** A run that ended, as the /admin dashboard shows it (#2138). */
+export interface LastJobRun {
+    startedAt: string;
+    completedAt: string;
+    status: 'completed' | 'failed';
+    /** The username who asked; null for a run its schedule started. */
+    ranBy: string | null;
+}
+/** A job's newest ended run (#2138), from {@link BackgroundJobManager.lastFinishedRun}. */
+export interface JobLastRun {
+    jobId: string;
+    displayName: string;
+    /** Null when it has never run — or, with `sinceStart`, not since this server started. */
+    lastRun: LastJobRun | null;
+    /** The job's history is kept in memory only (a maintenance tick, or no job state open): it starts empty at each start. */
+    sinceStart: boolean;
+}
 /**
  * A job type that can be registered with the BackgroundJobManager.
  */
@@ -343,6 +360,14 @@ declare class BackgroundJobManager extends BaseManager {
      * job's history.
      */
     scheduledJobView(jobId: string): Promise<ScheduledJobView | null>;
+    /**
+     * The newest run of a job that ended, completed or failed, and who asked
+     * for it (#2138) — what the /admin dashboard shows under Reindex and
+     * Rebuild. Read from the history already kept: the job state, and this
+     * process's own runs for what the state does not hold (a maintenance tick,
+     * or no state open). Null when no job of that id is registered.
+     */
+    lastFinishedRun(jobId: string): Promise<JobLastRun | 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. */

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

@@ -322,6 +322,18 @@ export declare function longestGapMs(schedule: Schedule, from: Date): number;
  * said nothing.
  */
 export declare function autoBackupSchedule(time: string, days: string, timeZone: string): ScheduleInput;
+/**
+ * The backup key file (#2134): what it is, for which site, the key's
+ * fingerprint, when it was saved (the server's local time), how to restore
+ * with it, and the one `NGDPBASE_BACKUP_KEY=` line, written so the boot's
+ * `.env` reader reads the key back exactly.
+ */
+export declare function backupKeyFileText(input: {
+    site: string;
+    fingerprint: string;
+    key: string;
+    saved: string;
+}): string;
 /**
  * The text of the critical "not restored" notification (#1876): what the
  * restore put back, what it did not, and per job the runs since the backup —
@@ -483,6 +495,18 @@ declare class BackupManager extends BaseManager {
      * sign-in; nothing else shows, logs or returns it.
      */
     revealBackupKey(): string | null;
+    /**
+     * The backup key as a small text file, for an admin to keep off the server
+     * without the rest of `.env` (#2134). The route asks `config-manage`, with
+     * its fresh sign-in. Recorded as `backup-key-download` (who and the
+     * fingerprint, never the key) before the file is made: on-failure refuse,
+     * so a record that cannot be written throws and nothing is sent. Null when
+     * the site has no backup key. Nothing is kept on the server.
+     */
+    revealBackupKeyFile(ctx: ActorContext): Promise<{
+        fingerprint: string;
+        text: string;
+    } | null>;
     /**
      * The instance `.env` exactly as it is on disk, backup key line included,
      * for an admin to keep a copy off the server (#1938). The route asks

package/lib/src/managers/BackupManager.js

@@ -15,7 +15,7 @@ import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, isLeftOutForNoK
 import { currentSharedFoldersKey, SHARED_FOLDERS_KEY_ENV, sharedFoldersKeyFingerprint } from '../utils/sharedFoldersKey.js';
 import { applyDeclaredPartsAtStart, archiveReader, archiveTarget, archiveWriter, backupDeclaredParts, placePartRecords, stageDeclaredParts, stageFilePart } from '../utils/directoryBackup.js';
 import { writeTreeArchive } from '../utils/treeArchive.js';
-import { envForBackup, envKeyNames, envKeyNamesFingerprint, INSTANCE_ENV_PART, instanceEnvPath } from '../utils/instanceEnvBackup.js';
+import { envFileLine, envForBackup, envKeyNames, envKeyNamesFingerprint, INSTANCE_ENV_PART, instanceEnvPath } from '../utils/instanceEnvBackup.js';
 import { readEnvLine } from '../utils/instanceEnvSecret.js';
 import { systemContext } from '../context/bootActions.js';
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -315,6 +315,24 @@ function localTime(iso) {
     const t = iso ? Date.parse(iso) : NaN;
     return Number.isFinite(t) ? new Date(t).toLocaleString() : 'an unknown time';
 }
+/**
+ * The backup key file (#2134): what it is, for which site, the key's
+ * fingerprint, when it was saved (the server's local time), how to restore
+ * with it, and the one `NGDPBASE_BACKUP_KEY=` line, written so the boot's
+ * `.env` reader reads the key back exactly.
+ */
+export function backupKeyFileText(input) {
+    return [
+        '# ngdpbase backup key',
+        `# Site: ${input.site}`,
+        `# Fingerprint: ${input.fingerprint}   (Admin → Backup on the restoring site must show the same)`,
+        `# Saved: ${input.saved}`,
+        '# Restore: put the line below in the new server\'s .env before it first starts (or replace its key, then restart).',
+        '# Keep this file off the server, somewhere as safe as a password manager. Anyone with this file and a backup can read that backup.',
+        envFileLine(BACKUP_KEY_ENV, input.key),
+        ''
+    ].join('\n');
+}
 /**
  * The text of the critical "not restored" notification (#1876): what the
  * restore put back, what it did not, and per job the runs since the backup —
@@ -925,6 +943,35 @@ class BackupManager extends BaseManager {
     revealBackupKey() {
         return currentBackupKey() || null;
     }
+    /**
+     * The backup key as a small text file, for an admin to keep off the server
+     * without the rest of `.env` (#2134). The route asks `config-manage`, with
+     * its fresh sign-in. Recorded as `backup-key-download` (who and the
+     * fingerprint, never the key) before the file is made: on-failure refuse,
+     * so a record that cannot be written throws and nothing is sent. Null when
+     * the site has no backup key. Nothing is kept on the server.
+     */
+    async revealBackupKeyFile(ctx) {
+        const key = currentBackupKey();
+        if (!key)
+            return null;
+        const fingerprint = backupKeyFingerprint(key);
+        const who = actorOf(ctx);
+        await recordAuditEvent(this.engine.getManager('AuditManager'), {
+            eventType: AUDIT_EVENT.BACKUP_KEY_DOWNLOAD,
+            ...who,
+            action: 'backup-key-download',
+            result: 'success',
+            severity: 'high',
+            resource: BACKUP_KEY_ENV,
+            resourceType: 'backup-key',
+            metadata: { ...who.metadata, fingerprint }
+        });
+        const name = this.setting('ngdpbase.application-name', '');
+        const baseUrl = this.setting('ngdpbase.application.base-url', '');
+        const site = (name && baseUrl ? `${name} (${baseUrl})` : name || baseUrl) || 'this site';
+        return { fingerprint, text: backupKeyFileText({ site, fingerprint, key, saved: localTime(new Date().toISOString()) }) };
+    }
     /**
      * The instance `.env` exactly as it is on disk, backup key line included,
      * for an admin to keep a copy off the server (#1938). The route asks

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

@@ -128,6 +128,11 @@ declare class ExportManager extends BaseManager {
      * with the reason, as `none` is.
      */
     private pdfProvider;
+    /**
+     * Is a PDF provider chosen (#2120)? The Export action offers PDF only then.
+     * Whether the chosen one works is known only by rendering, as before.
+     */
+    isPdfConfigured(): boolean;
     /** Log why, flag the manager (unless something worse is already shown), and refuse. */
     private pdfUnavailable;
     private acquirePdfSlot;
@@ -148,6 +153,17 @@ declare class ExportManager extends BaseManager {
      * @returns {Promise<string>} HTML content
      */
     exportPageToHtml(pageName: string, ctx: ActorContext, user?: ExportUser | null): Promise<string>;
+    /**
+     * One page as a complete HTML document: its content rendered, with the
+     * export's styling and metadata footer. It reads nothing: the caller has
+     * read the page through its door (the page export source, #2120).
+     *
+     * @param pageName - The page's name, its heading
+     * @param page - Its content and metadata
+     * @param user - User object for locale-aware formatting
+     * @returns The HTML document
+     */
+    renderPageDocument(pageName: string, page: PageForExport, user?: ExportUser | null): Promise<string>;
     /**
      * Export multiple pages to a single HTML file
      * @param {string[]} pageNames - Array of page names

package/lib/src/managers/ExportManager.js

@@ -182,6 +182,14 @@ class ExportManager extends BaseManager {
                 return new NonePdfProvider(`ngdpbase.export.pdf.provider '${name}' is not a PDF provider: use ${PDF_PROVIDERS.join(', ')}`);
         }
     }
+    /**
+     * Is a PDF provider chosen (#2120)? The Export action offers PDF only then.
+     * Whether the chosen one works is known only by rendering, as before.
+     */
+    isPdfConfigured() {
+        const name = this.engine.getManager('ConfigurationManager')?.getProperty('ngdpbase.export.pdf.provider', PDF_DEFAULTS.provider);
+        return (name ?? PDF_DEFAULTS.provider) !== 'none';
+    }
     /** Log why, flag the manager (unless something worse is already shown), and refuse. */
     pdfUnavailable(reason) {
         logger.warn(`[ExportManager] PDF export unavailable: ${reason}`);
@@ -248,6 +256,23 @@ class ExportManager extends BaseManager {
         if (!page) {
             throw new Error(`Page '${pageName}' not found`);
         }
+        return this.renderPageDocument(pageName, page, user);
+    }
+    /**
+     * One page as a complete HTML document: its content rendered, with the
+     * export's styling and metadata footer. It reads nothing: the caller has
+     * read the page through its door (the page export source, #2120).
+     *
+     * @param pageName - The page's name, its heading
+     * @param page - Its content and metadata
+     * @param user - User object for locale-aware formatting
+     * @returns The HTML document
+     */
+    async renderPageDocument(pageName, page, user = null) {
+        const renderingManager = this.engine.getManager('RenderingManager');
+        if (!renderingManager) {
+            throw new Error('Required managers not available');
+        }
         // Render the page content (without user context for exports)
         const renderedContent = await renderingManager.renderMarkdown(page.content, pageName, null);
         // Create full HTML document

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

@@ -0,0 +1,182 @@
+/**
+ * FileManager — the one door for files (#1852, epic #1851).
+ *
+ * It reads today's attachments as file records (src/types/File.ts): the
+ * shared pool as the public place, and every vault the requester may read.
+ * It writes through one door, `put` (#2148): a file goes into the place the
+ * caller chose, after the permission for that place, with AttachmentManager
+ * as the storage underneath; `placesWritableBy` lists the places a user may
+ * write to. Rename, move, delete and per-place indexes are later steps
+ * (docs/guides/storage-developer-guide.md).
+ *
+ * Read access is the existing rules, asked at this door:
+ * - the public place needs `asset-read`, from the PDP;
+ * - a vault is read through AttachmentManager's own vault reads, so the
+ *   container rule (owner or delegate, never a role, admin included) decides
+ *   exactly as it does for a vault page's files.
+ *
+ * The operator inventory (the migration dry run, #1859) is not on the
+ * engine's door: only an instance opened by {@link FileManager.openForOperator},
+ * from the command line, answers it.
+ */
+import BaseManager from './BaseManager.js';
+import { type AttachmentMetadata, type PutFile, type PutOptions, type UploadOptions } from './AttachmentManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type AttachmentDetail } from '../utils/auditEvents.js';
+import { type AssetRecord } from '../types/Asset.js';
+import type { FileInventory, FilePlace, FileRecord } from '../types/File.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type FileMigrationReport } from '../utils/fileMigrationPlan.js';
+/**
+ * What `put` hands back (#2149): the stored file's metadata, and, when
+ * vetting cleaned it, what was removed (one note per kind), so the uploader
+ * can be told.
+ */
+export type PutResult = AttachmentMetadata & {
+    cleaned?: string[];
+};
+/** A place the Upload file dialog offers (#2149): its key in the form, the words the user reads, and the place. */
+export interface UploadPlace {
+    key: string;
+    label: string;
+    place: FilePlace;
+}
+/** Where the Upload file dialog was opened (#2149): the page's path, and the page it shows, when there is one. */
+export interface UploadWhere {
+    path?: string;
+    pageName?: string;
+}
+declare class FileManager extends BaseManager {
+    /** Set only by {@link openForOperator}: this instance answers the inventory. */
+    private operatorInstance;
+    constructor(engine: WikiEngine);
+    /**
+     * Open the door read-only for an operator command (#1859): the site's
+     * configuration and attachment index, with nothing else started and
+     * nothing written. The site may be running; this process changes no file.
+     */
+    static openForOperator(): Promise<FileManager>;
+    /** Every file `ctx` may read, newest first; `place` narrows it to one place. */
+    list(ctx: ActorContext, filter?: {
+        place?: FilePlace;
+    }): Promise<FileRecord[]>;
+    /** The file with this id, when `ctx` may read it. */
+    get(id: string, ctx: ActorContext): Promise<FileRecord | null>;
+    /**
+     * The files named `filename` that `ctx` may read: one per place at most,
+     * since a name is unique within a place (today's pool can hold more than
+     * one, which is what the migration's suffixes are for). `place` narrows it.
+     */
+    findByName(filename: string, ctx: ActorContext, place?: FilePlace): Promise<FileRecord[]>;
+    /**
+     * The username a public record's uploader names (#2097): the uploader is
+     * stored as an identity @id, resolved through IdentityManager; an orphan,
+     * an @id with no account, `Unknown` or an email names no owner.
+     */
+    private ownerOf;
+    private readable;
+    /** `asset-read` for the public place, from the PDP. No PDP, no answer: closed. */
+    private mayReadPublic;
+    /**
+     * The places `ctx` may put a file in (#2148, operator 2026-10-30): the
+     * public place when the PDP grants `asset-upload`; each of the user's own
+     * vaults the vault rule lets them upload to (the default vault, and every
+     * vault they already have); each shared folder where they hold
+     * `shared-folder-file`. A place they may not write to is never listed.
+     *
+     * Each place is asked exactly as {@link put} asks it, so what is offered is
+     * what the door allows. An affordance: nothing is recorded.
+     */
+    placesWritableBy(ctx: ActorContext): Promise<FilePlace[]>;
+    /**
+     * Put a file in `place` (#2148): the one write door. The permission for
+     * that place is asked first, and a refusal stores nothing. Then ICE vets
+     * the file (#2149): its type from its bytes, and its format's shim cleans
+     * it; the cleaned copy is the one kept. AttachmentManager stores it as the
+     * place requires (sealed in a sealed vault or shared folder), and this door
+     * records the upload with what vetting removed (a sealed place's file by
+     * id only, #2048). No page decides the place: `options.pageName` is only
+     * the page that shows it.
+     *
+     * @throws Error 'Permission denied: …' when `ctx` may not write there, or
+     *   is nobody (#1926); a route answers it 401 or 403.
+     * @throws IceVetRefused when the file could not be checked; nothing is stored
+     */
+    put(ctx: ActorContext, place: FilePlace, file: PutFile, options?: PutOptions): Promise<PutResult>;
+    /**
+     * Record a file stored or deleted (#2149: moved here from AttachmentManager,
+     * which stores and records nothing itself). An upload is `continue`: a
+     * failed record is logged, never fatal. A delete is critical: it rethrows,
+     * tagged `AUDIT_WRITE_FAILED`, so the delete does not happen unrecorded and
+     * a caller can tell an unwritable record from a failed delete.
+     *
+     * A sealed store's file is recorded by id and store only (#2048), its
+     * owner by identity @id with the username beside it (#2041).
+     * AttachmentManager's delete door calls this until deleting is FileManager's.
+     */
+    recordFileEvent(op: 'upload' | 'delete', context: ActorContext, detail: AttachmentDetail, wikiContext?: {
+        request?: {
+            ip?: string;
+        } | null;
+    }): Promise<void>;
+    /**
+     * What the Upload file dialog offers `ctx` (#2149): every place
+     * {@link placesWritableBy} lists, and nothing else, each with the words the
+     * user reads; and the one selected at first: where they are working
+     * ({@link workingPlaceKey}), else the public place, else the first. Never
+     * inferred from whether a page exists. An affordance: nothing is recorded.
+     */
+    uploadPlaces(ctx: ActorContext, where?: UploadWhere): Promise<{
+        places: UploadPlace[];
+        defaultKey: string | null;
+    }>;
+    /** The place a dialog key names, when it is one `ctx` may write to (#2149); null otherwise. Never a place it was not offered. */
+    placeForKey(ctx: ActorContext, key: string): Promise<FilePlace | null>;
+    /** A place's key in the dialog: `public`, `vault:<id>` (always the user's own) or `folder:<name>`. */
+    static placeKey(place: FilePlace): string;
+    /** The words the user reads for a place. */
+    private placeLabel;
+    /**
+     * Where the user is working, as a dialog key (#2149): a shared folder's
+     * list (`/shared/<folder>`) or one of its pages is that folder; a page in
+     * one of their own vaults is that vault. Read from the location, never
+     * from whether a page by that name exists; anywhere else is no place.
+     */
+    private workingPlaceKey;
+    /**
+     * The place today's page-tied upload goes to (#1396, #1398, #2125), until
+     * #2149/#2150 move its callers to a place the user chose: an upload onto a
+     * shared folder's page goes into that folder, saved or not; onto a vault
+     * page into that page's vault, by someone who may edit the page; with the
+     * Private tick into the uploader's own vault (`store`, or their default);
+     * otherwise the public place.
+     */
+    placeForPageUpload(ctx: ActorContext, options: Pick<UploadOptions, 'pageName' | 'private' | 'store'>): Promise<FilePlace>;
+    /** May `ctx` put a file in `place`? The existing rule for each kind, asked of its owner. */
+    private mayPut;
+    /** The user's own vaults a file may go in: their default vault, and every vault they already have. */
+    private ownVaultIds;
+    private storeLayout;
+    /** A well-formed place: a vault is a user's (never the shared folders' container), with valid ids. */
+    private static isPlace;
+    /** A place in a log line. Ids only, never a file's name. */
+    private static describePlace;
+    /**
+     * Everything kept as files, for the migration dry run: the public files in
+     * full and each vault as counts (files, bytes, clash renames), never its
+     * names. Only on an instance opened by {@link openForOperator}, for an
+     * operator's context.
+     */
+    inventory(ctx: ActorContext): Promise<FileInventory>;
+    /** The dry run: the inventory, planned with the configured values. Writes nothing. */
+    migrationDryRun(ctx: ActorContext): Promise<FileMigrationReport>;
+    /** An asset record as a file record: the same fields, plus place, owner and system-category. */
+    static toFileRecord(asset: AssetRecord, place: FilePlace, owner: string | null, systemCategory: string | null): FileRecord;
+    private configManager;
+    /** The public place's category today: the default entry of `ngdpbase.system-category`. */
+    private defaultCategory;
+    /** The category that declares this vault, or null when none does. */
+    private vaultCategory;
+    private suffixDigits;
+}
+export default FileManager;