@jwilleke/ngdpbase-types 5.40.0 → 5.41.0

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

@@ -0,0 +1,320 @@
+import BaseManager, { type BackupFolder } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type RecoveryWordsExport } from '../utils/recoveryWordsFile.js';
+/** The folder every signed-in user may open (decision; the shipped `shared-folder-default` policy). */
+export declare const DEFAULT_SHARED_FOLDER = "default";
+/** The Executive shared folder (#2095); who opens it is the shipped policies' (`shared-folder-executive-read`, `shared-folder-executive-file`, `shared-folder-admin`). */
+export declare const EXECUTIVE_SHARED_FOLDER = "executive";
+/** The folders every site has, made once the recovery words are confirmed (#2125, #2095). */
+export declare const SHIPPED_SHARED_FOLDERS: readonly string[];
+/** Who may read and who may file in a folder, as the Shared folders screen sets it (#2126). */
+export interface SharedFolderAccess {
+    /** Roles granted `shared-folder-read` on `shared/<name>` by the screen's policy. */
+    read: string[];
+    /** Roles granted `shared-folder-file` on `shared/<name>` by the screen's policy. */
+    file: string[];
+}
+/** A policy in force that reaches a folder and that the screen did not write: shipped, an add-on's, or the site's own. Shown, never changed here. */
+export interface SharedFolderOtherPolicy {
+    id: string;
+    name: string;
+    effect: string;
+    /** Its subjects as written (`role:editor`, `job:nightly`); empty: everyone, anonymous visitors included. */
+    subjects: string[];
+    /** Which of `shared-folder-read` and `shared-folder-file` it decides, as the PDP matches actions (an empty list or `*` is both). */
+    actions: string[];
+    /** It has an id the screen writes for this folder: saving the folder is refused until it is renamed or removed. */
+    reserved: boolean;
+}
+/** The words waiting for this admin, as the confirm step needs them: never the words. */
+export interface WaitingWords {
+    token: string;
+    /** Whether they replace a set already saved (a new set, #2144). */
+    replacing: boolean;
+}
+/** What Admin → Backup shows about the organization's recovery words: never the words. */
+export interface SharedFoldersWordsInfo {
+    /** Which set (`recoveryWordsId`): what the admin's confirmation is bound to. */
+    wordsId: string;
+    madeAt: string;
+    shownTo: string;
+    /** Whether any folder key is sealed for this set: such a set can never be discarded. */
+    protectsFolders: boolean;
+}
+/** The door said no: not allowed, or the request does not fit the state. Nothing was changed. */
+export declare class SharedFolderRefusedError extends Error {
+    readonly name = "SharedFolderRefusedError";
+}
+/** The words typed back are not the ones shown (#2144). Nothing was saved; the words still wait, to be typed again. */
+export declare class SharedFolderWordsMismatchError extends SharedFolderRefusedError {
+    constructor();
+}
+/** The keys cannot be used right now (no server key, or not the one they were made under); the message says why. */
+export declare class SharedFoldersUnavailableError extends Error {
+    readonly name = "SharedFoldersUnavailableError";
+}
+declare class SharedFolderManager extends BaseManager {
+    readonly description = "The organization's shared folders: each folder's key, the organization key and the recovery words (#1775, #2124)";
+    private storageDir;
+    /** The 32-byte wrap key derived from `NGDPBASE_SHARED_FOLDERS_KEY`, read once at start; null without one. */
+    private wrapKey;
+    private keyFingerprint;
+    /** Why the keys cannot be used, or null when they can. */
+    private unavailable;
+    private file;
+    private readonly pending;
+    private readonly serial;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    shutdown(): Promise<void>;
+    private configuredStorageDir;
+    /** The wrapped keys are in the backup; a backup from before #2124 has none, so it is optional. */
+    backupFolders(): BackupFolder[];
+    /** The organization's recovery words as made (never the words), or null: none made yet. */
+    recoveryWordsInfo(): SharedFoldersWordsInfo | null;
+    /**
+     * Whether the admin shown the current words confirmed saving them, at the
+     * wording's current version: their consent in `shared-folders-recovery-words`
+     * for this set exists (ConsentManager's fact, asked each time). False with
+     * no words, no ConsentManager, or no wording page (then nobody could have
+     * confirmed what it says).
+     */
+    recoveryWordsConfirmed(): Promise<boolean>;
+    /** Why the keys cannot be used now, or null when they can. */
+    unavailableReason(): string | null;
+    /**
+     * Make the organization's 12 recovery words, to show to the admin `ctx`
+     * once (decision 4). Nothing is saved: the words wait, in memory only, for
+     * that admin's `saveRecoveryWords` with the returned token, for
+     * `ngdpbase.shared-folders.words-pending-minutes`. A second call replaces
+     * the first set unsaved. Refused while a set is saved: an unconfirmed set is
+     * discarded first (`discardUnconfirmedWords`), and a saved set is replaced
+     * with `prepareNewRecoveryWords`.
+     */
+    prepareRecoveryWords(ctx: ActorContext): Promise<{
+        token: string;
+        words: string[];
+    }>;
+    /**
+     * Make a new set of recovery words to replace the saved set (#2144): the
+     * admin `ctx`, with a fresh sign-in (`admin-system` and the step-up
+     * permission). Shown and confirmed exactly as the first set; nothing changes
+     * until `saveRecoveryWords` with all 12 typed back, which seals every folder
+     * key for the new words and retires the old ones. Abandoned or discarded
+     * (`discardRecoveryWords`), the old set stays.
+     */
+    prepareNewRecoveryWords(ctx: ActorContext): Promise<{
+        token: string;
+        words: string[];
+    }>;
+    /** Make 12 words and hold them, for `ctx` only, until saved, discarded or expired. Replaces any set waiting for them. */
+    private holdNewWords;
+    /** The words waiting for `ctx` to type them back, or null: none, or they expired. Never the words. */
+    waitingWords(ctx: ActorContext): WaitingWords | null;
+    /**
+     * The words waiting for `ctx`, to download as a file or print (#2144),
+     * while they still wait: once saved they are gone and cannot be made again.
+     * Recorded first as `recovery-words-export` (who, which set, how; never the
+     * words; on-failure refuse). Refused for a token that is not the one shown
+     * to them, or expired; the words are not discarded by a refused export.
+     */
+    pendingRecoveryWords(ctx: ActorContext, token: string, how: RecoveryWordsExport): Promise<{
+        words: string[];
+        madeAt: Date;
+        wordsId: string;
+    }>;
+    /** Forget the words shown to `ctx` and not saved: they are never shown again. A set they were to replace stays. */
+    discardRecoveryWords(ctx: ActorContext): void;
+    /** The words waiting for `ctx`, or undefined; expired words are forgotten. */
+    private livePending;
+    /**
+     * Discard the saved recovery words while the admin shown them has not
+     * confirmed saving them (operator, 2026-10-29): any holder of
+     * `admin-system` may, so a reminder that nobody can clear (that admin's
+     * account deleted, say) can always be cleared by making a new set and
+     * confirming it themselves. Refused once the set is confirmed, and while
+     * any folder key is sealed for it (`createFolderKey` needs a confirmed set,
+     * so such a set was confirmed once). Recorded as
+     * `shared-folder-words-discard` before the words are removed (on-failure
+     * refuse).
+     */
+    discardUnconfirmedWords(ctx: ActorContext): Promise<void>;
+    /**
+     * Save the recovery words shown to `ctx` (`prepareRecoveryWords` or
+     * `prepareNewRecoveryWords`) once they proved they kept them: `typed` is
+     * all 12 typed back (#2144). The caller asks for the tick first, and records
+     * the confirmation with ConsentManager after (`wordsId`).
+     *
+     * - A token that is not the one shown to them, or expired: refused, and the
+     *   words are discarded.
+     * - Words that do not match: `SharedFolderWordsMismatchError`; nothing is
+     *   saved and the words still wait, to be typed again.
+     * - The first set: recorded as `shared-folder-words-create`, then saved.
+     *   Refused when a set was saved meanwhile.
+     * - A new set (#2144): asks the fresh sign-in again, seals every folder key
+     *   again for the new words from its server-key wrap, records
+     *   `shared-folder-words-replace`, then writes the new set and the sealed
+     *   keys as one file renamed into place: the old words stop opening the
+     *   folders, and on any failure before that the old set stays as it was.
+     *   Refused when the saved set changed meanwhile.
+     *
+     * Each record is on-failure refuse, written before the save.
+     *
+     * @returns Which set of words was saved (`recoveryWordsId`)
+     */
+    saveRecoveryWords(ctx: ActorContext, token: string, typed: string): Promise<string>;
+    /**
+     * Every folder key in `folders`, its recovery copy sealed again for the
+     * words of `recovery` (#2144), opened with the server key. Nothing is
+     * written; a key that cannot be opened throws, and the caller keeps the
+     * old set.
+     */
+    private sealedForWords;
+    /**
+     * Make folder `folderId`'s own key (decision 2): a random key, wrapped
+     * under the server key and sealed for the recovery words, so it needs the
+     * words to exist and to be confirmed saved by the admin shown them
+     * (`recoveryWordsConfirmed`; operator, 2026-10-29): no folder key is ever
+     * protected only by words nobody saved. Recorded as `shared-folder-key-create` before it is
+     * saved (on-failure refuse). The key itself is not returned; open it with
+     * `openFolderKey`.
+     */
+    createFolderKey(ctx: ActorContext, folderId: string): Promise<void>;
+    /**
+     * Folder `folderId`'s key, unwrapped with the server key, for a caller the
+     * PDP permits `shared-folder-read` on the folder (#2125). The caller holds
+     * it for the moment it needs it and zeroes it. The page and file doors do
+     * not call this: they reach the key through the store I/O
+     * (`sharedFolderKeyFor`), only for a context permitted on the folder.
+     */
+    openFolderKey(ctx: ActorContext, folderId: string): Promise<Buffer>;
+    /** Folder `folderId`'s key with the server key, or undefined: no such folder, or the keys cannot be used. Never asks who; its callers have. */
+    private folderKey;
+    /** The folders there are, by name: each has its key. */
+    folderNames(): string[];
+    /**
+     * Make shared folder `name` (#2125): its key (`createFolderKey`, which
+     * needs the recovery words confirmed) and its place for pages, sealed with
+     * that key. Admins only (decision 8) until the Shared folders screen
+     * (slice 3). A new folder is opened by admins (`shared-folder-admin`) and
+     * read by executives (`shared-folder-executive-read`), and by nobody else
+     * until a policy names `shared/<name>`; `default` is shipped open to every
+     * signed-in user.
+     * Recorded as `shared-folder-create` before anything is made (on-failure
+     * refuse). Refused when it exists.
+     */
+    createFolder(ctx: ActorContext, name: string): Promise<void>;
+    /**
+     * Make the shipped folders (`SHIPPED_SHARED_FOLDERS`: `/shared/default` and
+     * `/shared/executive`) that are not there yet, once they can be made: the
+     * recovery words are confirmed. Finishing the words does this, and so does
+     * every start (`ensureShippedFoldersAtBoot`), so a site that confirmed its
+     * words before a shipped folder existed gets it on its next start.
+     * Idempotent. Returns the folders made now.
+     */
+    ensureShippedFolders(ctx: ActorContext): Promise<string[]>;
+    /**
+     * At start, make the shipped folders a site with confirmed words does not
+     * have yet (#2095), under the system context. Best-effort: a failure is
+     * logged and never blocks start-up; nothing is tried while the keys cannot
+     * be used.
+     */
+    ensureShippedFoldersAtBoot(): Promise<void>;
+    /**
+     * May `ctx` do `action` (a page or file action, or `shared-folder-read` /
+     * `shared-folder-file`) in folder `name`? The PDP's answer
+     * (`permitsInSharedFolder`); false for a folder that does not exist.
+     */
+    mayInFolder(ctx: ActorContext, action: string, name: string): Promise<boolean>;
+    /**
+     * The folders `ctx` may open (`shared-folder-read`), by name. Asking opens
+     * each one's key to this context (`sharedFolderKeyFor`), so the page and
+     * file doors can read what this reader may. The session middleware asks it
+     * on every request, so a grant removed ends access on the next request
+     * (decision 5).
+     */
+    foldersReadableBy(ctx: ActorContext): Promise<string[]>;
+    /**
+     * Record that `ctx` opened `what` (a page, its history, or a file) in
+     * folder `name` (`shared-folder-read`, on by default: every read of a
+     * shared folder is recorded, #1775). Called by what serves it, after the
+     * door allowed it. The writes are recorded by the page and file doors.
+     */
+    recordRead(ctx: ActorContext, name: string, what: {
+        page?: string;
+        attachmentId?: string;
+        action?: string;
+    }): Promise<void>;
+    /**
+     * Who may read and who may file in folder `name`, as the Shared folders
+     * screen set it: the roles its own policies (`shared-folder-access-<name>-read`
+     * / `-file`, in the site's custom configuration, in the shape the screen
+     * writes) name, and every other policy in force that reaches the folder,
+     * shown as it is, matched as PolicyEvaluator matches it. A policy with one of
+     * the screen's ids that the screen did not write is shown, marked
+     * `reserved`. `admin-system`, as the screen is. Display only: the PDP
+     * decides every access.
+     */
+    folderAccess(ctx: ActorContext, name: string): Promise<SharedFolderAccess & {
+        others: SharedFolderOtherPolicy[];
+    }>;
+    /** The roles a folder's access may name: every role there is but `anonymous`, by name. */
+    grantableRoles(): string[];
+    /**
+     * Set who may read and who may file in folder `name` (#2126, decision 8):
+     * writes the site's policies `shared-folder-access-<name>-read` (granting
+     * `shared-folder-read` on `shared/<name>`) and `-file` (`shared-folder-file`)
+     * to the roles given, through ConfigurationManager, and removes one whose
+     * list is empty. `admin-system`, with a fresh sign-in (the step-up
+     * permission, as every other configuration write asks). Refused for a folder
+     * that does not exist, a role that does not exist, `anonymous` (a folder is
+     * never public), and a folder one of whose ids holds a policy the screen did
+     * not write (it is never overwritten). Recorded as
+     * `shared-folder-access-change` (who, the folder, the roles before and
+     * after) once the write has succeeded; a failed write is recorded as a
+     * failure, and a record that cannot be written puts the policies back
+     * (on-failure refuse). ConfigurationManager records the configuration
+     * change as well. Nothing is written or recorded when nothing changes.
+     * Returns whether it changed.
+     *
+     * Only the screen's own policies change: a shipped or add-on policy, or one
+     * the site wrote elsewhere, still applies (`folderAccess` shows them).
+     */
+    setFolderAccess(ctx: ActorContext, name: string, access: SharedFolderAccess): Promise<boolean>;
+    /**
+     * Folder `name`'s access as the screen sees it: the screen's own policies
+     * (the site's entry under each id, in the shape `accessPolicy` writes), the
+     * ids holding a policy the screen did not write (the site's in another
+     * shape, a deny say, or one in force from a shipped or add-on layer), and
+     * the policies in force.
+     */
+    private accessState;
+    /** The site's own entries of the access policies (the custom configuration layer), as they are: never the shipped or an add-on's. */
+    private siteAccessPolicies;
+    /** The pages directory and the configured vault layout, where folders are kept. */
+    private pagesPlace;
+    /**
+     * Folder `folderId`'s key, opened with the recovery words instead of the
+     * server key: what recovery after a lost server key will use (a later
+     * slice: a new server key, every folder key rewrapped). Throws when the
+     * words are wrong. Works with no server key at all.
+     */
+    openFolderKeyWithWords(ctx: ActorContext, folderId: string, words: string): Promise<Buffer>;
+    private requireAdmin;
+    /**
+     * The fresh sign-in a new set of words (#2144) and an access change (#2126)
+     * need: the PDP applies step-up to `FRESH_SIGN_IN_PERMISSION`, and never
+     * grants it to a delegated credential (an agent token).
+     */
+    private requireFreshSignIn;
+    /** The wrap key, or throws why there is none to use. */
+    private requireUsable;
+    private pendingMinutes;
+    private fileOrNew;
+    private keysPath;
+    private readKeysFile;
+    /** Owner-only, written whole and renamed into place, so a crash never leaves half a file. */
+    private writeKeysFile;
+}
+export default SharedFolderManager;

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

@@ -68,8 +68,12 @@ export interface ScanResult {
     skippedTruncated?: boolean;
     /** Number of indexed items with no usable capture date (EXIF/QuickTime) — they sort by file mtime (#807) */
     noCaptureDate?: number;
+    /** Paths of the first items counted in `noCaptureDate`, capped; the count stays exact (#2191) */
+    noCaptureDateFiles?: string[];
     /** Number of indexed items with a partial (year-only / year+month) EXIF date, defaulted to Jan 1 (#808) */
     partialCaptureDate?: number;
+    /** Paths of the first items counted in `partialCaptureDate`, capped; the count stays exact (#2191) */
+    partialCaptureDateFiles?: string[];
     /** Number of stale index entries pruned because their file vanished from a scanned folder (#867) */
     removed?: number;
     /** Total elapsed time in milliseconds */

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

@@ -221,6 +221,12 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
      * Patterns ending with `/` are directory-only; all others match both files and dirs.
      */
     private matchesIgnorePattern;
+    /**
+     * Add a file to a capture-date list until CAPTURE_DATE_LIST_CAP (#2191).
+     * The path is relative to the media folder it was found under, so the
+     * notice and its email do not disclose the server's storage layout.
+     */
+    private listCaptureDateFile;
     /**
      * Process a single media file: stat, EXIF read, index update.
      */

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

@@ -131,9 +131,10 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * {@link permits}, which is "may it act now", and named so: an affordance
      * (show the reveal button, show the sign-in methods section) asks this, so a
      * person whose sign-in is not fresh still sees the way to the prompt that
-     * makes it fresh. A door never asks this.
+     * makes it fresh. A door never asks this. `on` asks it about a resource,
+     * as {@link decide} does (#2120: a vault page's export).
      */
-    holds(subject: DecisionInput, action: string): Promise<boolean>;
+    holds(subject: DecisionInput, action: string, on?: Omit<DecisionRequest, 'action'>): Promise<boolean>;
     /**
      * Step-up (#1525, #1635), decided here — in the one place every door asks —
      * rather than by routes in front of the doors. A permission marked

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

@@ -1,6 +1,6 @@
 /** Every permission core declares. Addons generate their own union. */
 export type CorePermission = 
-/** Change what protects your own account — password, email, sign-in methods (passkeys), vault takeout and import, approving a device (#1525). Granted wherever profile-manage is; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
+/** Change what protects your own account — password, email, sign-in methods (passkeys), vault takeout and import, approving a device (#1525). Granted wherever profile-manage is; asks for a fresh sign-in, because the entry carries "step-up": true (#1638) */
 'account-security'
 /** View administration screens (read-only, no changes) */
  | 'admin-read'
@@ -20,7 +20,7 @@ export type CorePermission =
  | 'audit-export'
 /** Add a comment, and delete your own; deleting anyone's is admin-system (#1198) */
  | 'comment-create'
-/** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
+/** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in, because the entry carries "step-up": true (#1638) */
  | 'config-manage'
 /** Open the Executive Hub (/executive): the organization's summary cards and the requests waiting for the board (#2093). Held by the executive role; deciding a request still needs that request's own permission */
  | 'executive-read'
@@ -54,7 +54,7 @@ export type CorePermission =
  | 'search-page'
 /** Search users */
  | 'search-user'
-/** Unmask a configuration secret (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up. Hashed credentials (agent tokens) and shown-once secrets can never be revealed */
+/** Unmask a configuration secret (#1525). Admin only by default; asks for a fresh sign-in, because the entry carries "step-up": true (#1638). Hashed credentials (agent tokens) and shown-once secrets can never be revealed */
  | 'secret-reveal'
 /** End another person's signed-in session (#1638) */
  | 'session-revoke'

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

@@ -0,0 +1,90 @@
+/**
+ * The file record (#1852, epic #1851): one shape for every file the site
+ * keeps, read through `FileManager`, the one door.
+ *
+ * The decisions behind it are the epic's decision log
+ * (https://github.com/jwilleke/ngdpbase/issues/1851#issuecomment-6236003946);
+ * the practice is docs/guides/storage-developer-guide.md.
+ *
+ * It is not a new vocabulary. `AssetRecord` (src/types/Asset.ts) is already
+ * the internal, schema.org-named shape for a stored file (docs/schemas.md
+ * Decision 11), so the record takes its fields from there by name and adds
+ * only what an asset record does not say: where the file lives, who owns it,
+ * and its system-category. A field that changes in `AssetRecord` changes
+ * here too; there is no second copy to drift.
+ */
+import type { AssetRecord } from './Asset.js';
+/**
+ * Where a file lives: the public area, one user's vault, or one shared
+ * folder. A file is unique by its place plus its name; the same name may
+ * exist in two places.
+ *
+ * Each place is named by the identifiers the site already uses: a vault by
+ * its owner's username and its vault id (`pages/vaults/{owner}/{vault}/`), a
+ * shared folder by its name (`/shared/{folder}`, SharedFolderManager). The
+ * shared folders' internal container (`SHARED_FOLDER_OWNER`) is never a
+ * vault owner here: a folder is always `{ kind: 'shared-folder' }` (#2148).
+ */
+export type FilePlace = {
+    kind: 'public';
+} | {
+    kind: 'vault';
+    owner: string;
+    vault: string;
+} | {
+    kind: 'shared-folder';
+    folder: string;
+};
+/**
+ * One file, as the door shows it.
+ *
+ * From `AssetRecord`, unchanged in meaning:
+ * - `id`: the stable identity, kept across renames and moves.
+ * - `filename`: the file's name, the one links use (`[Annual Report.pdf]`),
+ *   unique within its place.
+ * - `name`: the human title, when one was given (schema.org `name`).
+ * - `description`, `keywords`: descriptive metadata.
+ * - `encodingFormat`: the media type (`application/pdf`, `image/png`…).
+ * - `contentSize`, `url`, `mentions` (the pages that show it).
+ * - `dateCreated` / `author`: when and by whom it was created, as recorded
+ *   (the uploader; a legacy record may say `Unknown`).
+ * - `dateModified` / `editor`: when and by whom it last changed.
+ *
+ * Added here:
+ * - `place`: public, a vault, or a shared folder.
+ * - `owner`: the user it belongs to. A vault's files are the vault owner's.
+ *   A public file's owner is its uploader when the record names a user, or
+ *   `null` when it does not (`Unknown`, empty, an email used as a name):
+ *   the migration gives those an owner from configuration.
+ * - `systemCategory`: the category whose rules apply. Per file, never by
+ *   type. A public file today is the default category's; a vault file is
+ *   the category that declares its vault, or `null` when none does.
+ */
+export type FileRecord = Pick<AssetRecord, 'id' | 'filename' | 'name' | 'description' | 'keywords' | 'encodingFormat' | 'contentSize' | 'url' | 'mentions' | 'dateCreated' | 'author' | 'dateModified' | 'editor'> & {
+    place: FilePlace;
+    owner: string | null;
+    systemCategory: string | null;
+};
+/**
+ * What the operator inventory shows of one vault (#1859's dry run). Counts
+ * only: a vault's names, owners and metadata belong to its owner and never
+ * leave the door. A sealed vault can't be read without its owner's key, so
+ * only what is on disk is counted (bytes as stored, sealed) and its clashes
+ * are unknown (`null`).
+ */
+export interface VaultFileSummary {
+    owner: string;
+    vault: string;
+    systemCategory: string | null;
+    /** Whether its index could be read. False for a sealed vault (no key here) or one refused as not yet opened. */
+    readable: boolean;
+    files: number;
+    bytes: number;
+    /** Files that would get a `-###` suffix in this vault; `null` when it can't be read. */
+    clashes: number | null;
+}
+/** Everything the site keeps as files, for the operator (#1859): the public files in full, each vault as counts. */
+export interface FileInventory {
+    publicFiles: FileRecord[];
+    vaults: VaultFileSummary[];
+}

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

@@ -17,7 +17,7 @@
  */
 import type { ShareGrant } from './Share.js';
 import type { ProxyClaim } from '../managers/UserManager.js';
-import type { SignInRecord, PendingConnection, OutsideChoice, PendingStepUp } from '../managers/AuthManager.js';
+import type { SignInRecord, PendingConnection, OutsideChoice, PendingStepUp, StepUpPrompt } from '../managers/AuthManager.js';
 declare module 'express-session' {
     interface SessionData {
         csrfToken?: string;
@@ -44,6 +44,8 @@ declare module 'express-session' {
         pendingStepUp?: PendingStepUp;
         /** The path whose next page view says "Confirmed — you can do it now" after a step-up (#2145). */
         stepUpConfirmed?: string;
+        /** A script's step-up prompts (#2193), the newest few: each id and whether it was confirmed or cancelled. */
+        stepUpPrompts?: StepUpPrompt[];
         /** A sign-in waiting for its second factor: the handle, and where to go after (#1523). No identity yet. */
         pendingSignIn?: string;
         pendingRedirect?: string;

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

@@ -60,6 +60,8 @@ declare module 'linkedom' {
     getElementById(id: string): LinkedomElement | null;
     querySelector(selector: string): LinkedomElement | null;
     querySelectorAll(selector: string): LinkedomElement[];
+    /** The whole document as HTML, its doctype included. */
+    toString(): string;
   }
 
   function parseHTML(html: string): { document: LinkedomDocument };

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

@@ -170,6 +170,8 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_EXTEND: "share-extend";
     /** Share link revoked; pairs with token-revoke */
     readonly SHARE_REVOKE: "share-revoke";
+    /** An administrator changed who may read and who may file in a shared folder on the Shared folders screen (#2126): which folder, who, and the roles before and after for each. Recorded once the folder's policies are written; a failed write is recorded as a failure, with the error, and a record that cannot be written puts the policies back */
+    readonly SHARED_FOLDER_ACCESS_CHANGE: "shared-folder-access-change";
     /** An administrator created a shared folder (#2125): which folder and who. Recorded before the folder is made, which cannot proceed without it */
     readonly SHARED_FOLDER_CREATE: "shared-folder-create";
     /** A shared folder's own key was made (#2124): which folder and who, never the key. Recorded before the key is saved, which cannot proceed without it */

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

@@ -177,6 +177,8 @@ export const AUDIT_EVENT = {
     SHARE_EXTEND: 'share-extend',
     /** Share link revoked; pairs with token-revoke */
     SHARE_REVOKE: 'share-revoke',
+    /** An administrator changed who may read and who may file in a shared folder on the Shared folders screen (#2126): which folder, who, and the roles before and after for each. Recorded once the folder's policies are written; a failed write is recorded as a failure, with the error, and a record that cannot be written puts the policies back */
+    SHARED_FOLDER_ACCESS_CHANGE: 'shared-folder-access-change',
     /** An administrator created a shared folder (#2125): which folder and who. Recorded before the folder is made, which cannot proceed without it */
     SHARED_FOLDER_CREATE: 'shared-folder-create',
     /** A shared folder's own key was made (#2124): which folder and who, never the key. Recorded before the key is saved, which cannot proceed without it */

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

@@ -163,6 +163,8 @@ export type AttachmentDetail = {
     stored?: false;
     heldAs?: string;
     offeredAs?: string;
+    /** What vetting removed before the file was kept (#2149): one note per kind, counts only, never content. */
+    cleaned?: string[];
 }
 /** A sealed store's file: `owner` is the store owner's identity @id in the record, `ownerUser` their username beside it (#2041). */
  | {
@@ -172,6 +174,7 @@ export type AttachmentDetail = {
         store: string;
         ownerUser?: string;
     };
+    cleaned?: string[];
 };
 export type AttachmentInput = CommonInput & {
     op: AttachmentOp;

package/lib/src/utils/auditEvents.js

@@ -169,6 +169,9 @@ export function buildAttachmentAuditEvent(input) {
                 metadata.offeredAs = input.offeredAs;
         }
     }
+    // #2149: what vetting removed, in either form: kinds and counts, nothing of the file.
+    if (input.cleaned && input.cleaned.length > 0)
+        metadata.cleaned = [...input.cleaned];
     const severity = op === 'delete'
         ? (viaToken ? 'high' : 'medium')
         : (viaToken ? 'medium' : 'low');

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

@@ -0,0 +1,81 @@
+/**
+ * The files migration dry run (#1859, epic #1851): what copying today's
+ * attachments into files WOULD do, worked out from the door's inventory
+ * (`FileManager.inventory`). Pure: it reads nothing and writes nothing.
+ *
+ * The rules are the decision log's
+ * (https://github.com/jwilleke/ngdpbase/issues/1851#issuecomment-6236003946):
+ * - two different files with the same name in one place get a numeric
+ *   suffix, `report.pdf` and `report-001.pdf`;
+ * - each page that shows a renamed file is rewritten to its new name, so it
+ *   keeps showing its own file;
+ * - an unknown or invalid uploader gets an owner from configuration.
+ */
+import type { FileInventory, FileRecord, VaultFileSummary } from '../types/File.js';
+/** The configured values the plan applies (`ngdpbase.files.migration.*`). */
+export interface FileMigrationOptions {
+    /** Recorded uploader → username, applied first (`owner-map`). */
+    ownerMap: Record<string, string>;
+    /** Owner for a file whose record names no user (`default-owner`). */
+    defaultOwner: string;
+    /** Width of the clash suffix: 3 gives `-001` (`clash-suffix-digits`). */
+    suffixDigits: number;
+}
+/** A file the migration would give a new name, and the pages it would rewrite to it. */
+export interface PlannedRename {
+    id: string;
+    from: string;
+    to: string;
+    pages: string[];
+}
+/** Who a group of public files would belong to after the migration. */
+export interface PlannedOwner {
+    /** The uploader the record names, or `null` when it names none. */
+    recorded: string | null;
+    owner: string;
+    /** `kept`: the record names a user; `mapped`: `owner-map`; `default`: `default-owner`. */
+    how: 'kept' | 'mapped' | 'default';
+    files: number;
+}
+export interface FileMigrationReport {
+    publicFiles: {
+        count: number;
+        bytes: number;
+        byType: Array<{
+            type: string;
+            files: number;
+        }>;
+    };
+    owners: PlannedOwner[];
+    /** Public files whose record names no user (before the owner mapping). */
+    noOwner: number;
+    /** Each clashing name, with the renames it would get. */
+    clashes: Array<{
+        name: string;
+        files: number;
+        renames: PlannedRename[];
+    }>;
+    /** Each page that would be rewritten, and to which names. */
+    pagesToRewrite: Array<{
+        page: string;
+        changes: Array<{
+            from: string;
+            to: string;
+        }>;
+    }>;
+    vaults: VaultFileSummary[];
+}
+/** The `-###` name a clash gets: before the extension, `route.png` → `route-001.png`. */
+export declare function suffixedName(name: string, n: number, digits: number): string;
+/**
+ * The new name of every file in one place that shares its name with another
+ * (id → new name). The oldest keeps the name (then the lowest id, so the
+ * answer is the same on every run); the rest are numbered from 1 in that
+ * order, skipping any name already used in the place. Names match exactly,
+ * as a link finds a file today.
+ */
+export declare function planClashRenames(files: ReadonlyArray<Pick<FileRecord, 'id' | 'filename' | 'dateCreated'>>, digits: number): Map<string, string>;
+/** What the migration would do with this inventory. */
+export declare function planFileMigration(inventory: FileInventory, opts: FileMigrationOptions): FileMigrationReport;
+/** The report as the operator reads it. */
+export declare function formatFileMigrationReport(r: FileMigrationReport, header?: string[]): string;