@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

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

@@ -32,7 +32,8 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import { IContentConverter } from '../converters/IContentConverter.js';
 import { type ZipReadLimits } from '../utils/zipArchive.js';
 import { type JobContext } from '../context/JobContext.js';
-import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RecentImport, RegisteredShim } from '../ice/types.js';
+import { type IceNameForm } from '../ice/givenName.js';
+import type { IceExportFormat, IceExportReport, IceExportRequest, IceExportSource, IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, IceTarget, IceUpload, IceVetResult, RecentImport, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
  */
@@ -217,6 +218,31 @@ export declare class ImportUploadRefused extends Error {
     readonly reason: string;
     constructor(file: string, reason: string);
 }
+/**
+ * An export that is not started (#2120): the thing is not there, the user may
+ * not export it, or the format is not one offered for it. A route answers it
+ * as "not found", so it never tells the user which.
+ */
+export declare class IceExportRefused extends Error {
+    constructor(message?: string);
+}
+/**
+ * An export not started because too much is already being made (#2120): the
+ * user's own queued exports are at `max-queued-per-user`, or every held run is
+ * still being made. A route answers it as 429; nothing was read or queued.
+ */
+export declare class IceExportBusy extends Error {
+    constructor(message: string);
+}
+/**
+ * An export refused only because the user's sign-in is not fresh enough
+ * (#2120): they hold `permission` on the thing, and step-up asks for it. A
+ * route answers it with the step-up prompt, not "not found".
+ */
+export declare class IceExportNeedsFreshSignIn extends Error {
+    readonly permission: string;
+    constructor(permission: string);
+}
 /** One page's outcome in a takeout import (#1472). */
 export type TakeoutPageOutcome = {
     title: string;
@@ -269,13 +295,13 @@ export interface UsableReceiver {
     label?: string;
     /** What the screen offers; the kept types (`types`, #2061) are the upload door's business, not the screen's. */
     originals: Required<Omit<IceOriginalChoices, 'types'>>;
+    /** What a name the user gives becomes (#2130), when the receiver takes one: the screen offers the field only then. */
+    names?: IceNameForm;
+    /** Where within it this user may import (#2118), for a receiver with places: the screen offers a choice of them. */
+    targets?: IceTarget[];
 }
-/**
- * Import Manager class
- *
- * Manages content import with extensible format support via converter registry.
- */
 declare class ImportManager extends BaseManager {
+    #private;
     /** Registry of format converters */
     private converterRegistry;
     /** ICE (#1979): shims by id (`<owner>.<name>`), in registration order. */
@@ -284,13 +310,19 @@ declare class ImportManager extends BaseManager {
     private readonly receiverRegistry;
     /** ICE: runs this process knows about, oldest first. */
     private readonly iceRuns;
-    /** ICE: runs waiting for the background job, each with its own context. */
+    /** ICE (#2171): a rechecking run's store, as fingerprint → id, read once per run and store; dropped when the run ends. */
+    private readonly storeHoldings;
+    /** ICE: work waiting for the background job, each with its own context: an import run or an export (#2120). */
     private readonly iceQueue;
     /** ICE: true while a background job is draining the queue. */
     private iceDraining;
     /** ICE: the last background run id the queue was handed to. */
     private iceLastJobRunId;
     private iceLedger;
+    /** ICE export (#2120): the owners' doors for reading what is exported, by id. */
+    private readonly exportSourceRegistry;
+    /** ICE export: runs this process holds, oldest first, each with its file once made. Never written to disk. */
+    private readonly exportRuns;
     constructor(engine: WikiEngine);
     /**
      * Initialize the manager
@@ -316,7 +348,9 @@ declare class ImportManager extends BaseManager {
     /**
      * Register a receiver (D4): a door that already exists. Core's are
      * `core.pages` and `core.files`; an add-on registers its own manager's door
-     * through `host.registerReceiver`.
+     * through `host.registerReceiver`. Refuses `writesEncrypted` from every
+     * caller, whatever owner it names: core registers its own receivers
+     * through the private `#registerReceiver` (#2179).
      *
      * @returns The receiver's id, `<owner>.<name>`
      */
@@ -333,18 +367,49 @@ declare class ImportManager extends BaseManager {
      * (D11), for the import screen (#2021).
      */
     receiversFor(ctx: ActorContext): Promise<UsableReceiver[]>;
+    /**
+     * Why a name the user gave cannot be used for this receiver (#2130), or
+     * null when it can: the engine's one rule (`givenNameProblem`), with the
+     * site's `ngdpbase.import.engine.name-max-length`. A receiver that names
+     * what it creates itself (no `names`) takes no name at all. For the import
+     * screen, to answer at once; the engine checks again in the run.
+     */
+    givenNameProblem(receiverId: string, given: string, original: string): string | null;
     /**
      * The original-file choices a receiver offers (D11, #2021): what it
      * declares, else all three; its default when it names one it allows, else
      * `ngdpbase.import.engine.default-original` when allowed, else the first.
      */
     private originalChoices;
+    /**
+     * The request's place within the receiver, checked (#2118): one the
+     * receiver's `targets` gives this context, for a receiver with places,
+     * and none for any other. An unknown receiver is left for the run to report.
+     *
+     * @throws Error when the place is missing, not this user's, or not the receiver's
+     */
+    private checkTarget;
     /**
      * The request as the engine runs it: the receiver's default original when
      * none was chosen, and a refusal for a choice the receiver does not offer
      * (D11, #2021). An unknown receiver is left for the run to report.
      */
     private withOriginal;
+    /**
+     * Vet one file before it is kept as a file (#2149): its type from its
+     * bytes (#1624), then its format's shim, when that shim is switched on,
+     * cleans it. FileManager asks this for every file it stores, and keeps the
+     * bytes returned, never the ones it sent; `removed` says what was taken
+     * out, for the uploader and the upload's record.
+     *
+     * Runs in the caller's request: cleaning is one linear pass over a file no
+     * larger than the site's upload limit. It decides nothing about permission:
+     * the caller has asked that first.
+     *
+     * @param ctx - Who is keeping the file (P1); only named in the log line when something was cleaned
+     * @throws IceVetRefused when the cleaning shim fails: the file could not be checked, so it is not kept
+     */
+    vetFile(upload: IceUpload, ctx: ActorContext): Promise<IceVetResult>;
     /**
      * Run one import now and wait for it. For code already off the request
      * path: an add-on's own background job, a test. A route uses
@@ -372,6 +437,11 @@ declare class ImportManager extends BaseManager {
      * the store's sealed index entry written. Each is recorded in the ledger
      * as the keep-once record (#2011), so the run reuses it and needs no key.
      *
+     * A receiver whose `receive` itself may write into an encrypted store
+     * (`writesEncrypted`, #2118) has the whole run now, in this request, with
+     * `ctx` and its key, and the run's id is returned when it has ended: no
+     * key is ever carried into a job (#2034).
+     *
      * @throws ImportUploadRefused when an original could not be kept; nothing is queued
      */
     enqueueUpload(request: IceRunRequest, ctx: ActorContext): Promise<string>;
@@ -396,14 +466,105 @@ declare class ImportManager extends BaseManager {
     /**
      * Is an import into this receiver confidential (#2110)? Only when its
      * destination is encrypted: a receiver that keeps into a sealed store
-     * (`keepsEncrypted`). No receiver can declare itself so otherwise. A
+     * (`keepsEncrypted`), or whose own door writes into one
+     * (`writesEncrypted`, #2118). No receiver can declare itself so otherwise. A
      * confidential import's file names are shown to the uploader and kept in
-     * the audit log, and never written to application logs, notices or admin
-     * screens; every other import logs them as before.
+     * the audit log, and never written to application logs, notices, admin
+     * screens or the import ledger (#2161); every other import logs them as before.
      */
     isConfidential(receiverId: string): boolean;
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
+    /**
+     * Register an export source (#2120): the owner's door for reading what is
+     * exported, checking its existing read permission (D5). Core's is
+     * `core.pages`.
+     *
+     * @returns The source's id, `<owner>.<name>`
+     * @throws Error when the source is malformed or its id is taken
+     */
+    registerExportSource(owner: string, source: IceExportSource): string;
+    /**
+     * The formats the Export action offers this context for one thing (#2120):
+     * none when the source's owner would not let it export the thing (asked
+     * as an affordance, recording nothing), else each `out` shim, switched on,
+     * that can make a file from what the source yields.
+     */
+    exportFormatsFor(sourceId: string, ref: string, ctx: ActorContext): Promise<IceExportFormat[]>;
+    /**
+     * Start an export (#2120), from the request that asked: the source reads
+     * the thing now, with the request's own context, so its owner's door
+     * decides with everything the request carries (step-up, a vault's key)
+     * and records the export. The shims run off the request path, in the ICE
+     * background job, as the user's own job context. Returns the run id at once.
+     *
+     * Before anything is read, the user may have at most
+     * `max-queued-per-user` exports queued or running, and a held run must be
+     * free to make room under `max-kept-runs`. Once read, the items count
+     * toward `max-held-bytes` until their file is made.
+     *
+     * @throws IceExportRefused when the thing is not there, the user may not
+     *   export it, or the format is not one offered for it
+     * @throws IceExportNeedsFreshSignIn when the user holds the permission but
+     *   step-up asks for a fresh sign-in
+     * @throws IceExportBusy when the user, or the site, is making as many
+     *   exports as it may
+     * @throws IceExportFailed when the thing is larger than this site exports
+     */
+    startExport(request: IceExportRequest, ctx: ActorContext): Promise<string>;
+    /** An export's status, to the user it runs as; null to anyone else, and once it is let go. */
+    getExportRun(runId: string, ctx: ActorContext): IceExportReport | null;
+    /** An export's file, to the user it runs as, while it is kept; null otherwise. */
+    exportFile(runId: string, ctx: ActorContext): {
+        name: string;
+        mediaType: string;
+        bytes: Buffer;
+    } | null;
+    /** The source's formats now: the enabled out shims' chains from what it yields. */
+    private exportChainsFor;
+    private executeExport;
+    /** The source's own record of how an export ended, if it keeps one; a record that fails is logged, never thrown. */
+    private recordExportOutcome;
+    /**
+     * Before a new export is read (#2120): refuse when the user already has
+     * `max-queued-per-user` exports queued or running, and let finished runs go
+     * until there is room under `max-kept-runs`. A queued or running run is
+     * never let go.
+     *
+     * @throws IceExportBusy when there is no room
+     */
+    private makeRoomForExport;
+    /**
+     * Hold a new run with the bytes its items take until its file is made,
+     * which count toward `max-held-bytes` (#2120). Finished files are let go
+     * to make room, the user's own first ({@link finishedExportRuns}).
+     *
+     * @throws IceExportFailed when the items alone are more than it may hold
+     * @throws IceExportBusy when queued and running exports alone hold too much
+     */
+    private holdExportRun;
+    /**
+     * Keep a made file in memory until `keep-minutes` have passed, never on
+     * disk: an export of a sealed vault's page must not rest unencrypted. Its
+     * items' bytes are released for the file's. Other finished files are let
+     * go when all would hold more than `ngdpbase.export.engine.max-held-bytes`,
+     * the user's own first.
+     */
+    private keepExportFile;
+    /** Let finished files go, `username`'s own first, until all held bytes are at most `limit`. */
+    private letFilesGo;
+    /** Every byte exports hold: made files, and the items of runs not yet made. */
+    private heldExportBytes;
+    /**
+     * The runs that may be let go, in the order they are: done or failed only,
+     * `username`'s own oldest first, then everyone else's oldest first, so one
+     * user's exports push out their own before anyone else's (#2120).
+     */
+    private finishedExportRuns;
+    private dropExportRun;
+    /** `ngdpbase.export.engine.*`: every limit an export applies is configuration (the chain's length is import's). */
+    private exportSettings;
+    private exportManager;
     /**
      * The ledger scope a run uses (#2013): bound to the receiver and to the user
      * `ctx` names, by their identity `@id`; their username only when the
@@ -430,7 +591,7 @@ declare class ImportManager extends BaseManager {
     private enabledShims;
     /**
      * Hand the queue to the background job. One job run drains every queued
-     * import, each under its own context. A job run that has finished draining
+     * import and export, each under its own context. A job run that has finished draining
      * but is not yet marked done answers `enqueue` with its old run id; then
      * try again shortly, so nothing queued is stranded.
      */
@@ -455,15 +616,101 @@ declare class ImportManager extends BaseManager {
      * `core.pages` (D4): NCM into pages, through PageManager's save door, as the
      * folder import saves. It checks `page-create` itself (D5). A title that
      * already exists is a duplicate, as it is for the folder import by default.
+     * A title the user gave (#2130) replaces the one the file gives; when a
+     * page has it already, the item is refused, never saved over that page.
      */
     private pagesReceiver;
     /**
-     * `core.files` (D4): a file through AttachmentManager's upload door, which
-     * checks `asset-upload` itself. Also where a kept original goes (D11) when
-     * the chosen receiver does not keep its own. It becomes FileManager's write
-     * door once the files layer has one (#1851).
+     * `page-export` for this page (#2120). For a page in a vault, asked about
+     * the page as the route door asks it (`hasPermissionOn`, #1539): the
+     * container rule, then the capability with the page's vault, so a
+     * site-wide role does not reach in. For any other page, the capability.
+     * An affordance asks whether it is held (no step-up); the door whether it
+     * is permitted, and a refusal to someone who holds it is step-up's.
+     */
+    private mayExportPage;
+    /**
+     * `core.pages` as an export source (#2120, D5: pages export checks
+     * `page-export`). A page is offered for export when its reader may see it
+     * and holds `page-export` (affordances, recording nothing). Reading it
+     * for export asks `page-export` ({@link mayExportPage}), then reads through the page
+     * door (`readPage`), which decides `page-read` on the page and records a
+     * refusal. The export is recorded as `page-export`, with the format and
+     * the run, once the run has ended: a success only when the file was made.
+     */
+    private pagesExportSource;
+    /**
+     * `core.files` (D4): a file into the public place through FileManager's
+     * write door, `put` (#2149), which asks `asset-upload` itself and vets the
+     * file. Also where a kept original goes (D11) when the chosen receiver does
+     * not keep its own. A name the user gave (#2130)
+     * is the stored file's name; when the shared pool has a file of that name
+     * already, the item is refused, never stored beside or over it.
      */
     private filesReceiver;
+    /**
+     * `core.private-store` (#2118): a takeout (#1387) handed back into one of
+     * its owner's own private stores, read by the shim `core.takeout`. It
+     * replaces the takeout import's own door (#1472). Each page goes through
+     * PageManager's save door and each file through FileManager's write door
+     * (`put`), the doors an edit and an upload use, so a sealed store
+     * encrypts on write with no new crypto.
+     *
+     * - No new permission (D5): the rule the takeout import always had, the
+     *   `account-security` permission and the user's own private container.
+     * - Its places (`targets`) are the user's own stores this context can
+     *   write now: those on disk and the default one, an encrypted one only
+     *   while it is unlocked in this session.
+     * - Its writes may be sealed (`writesEncrypted`): the engine runs an
+     *   upload into it in the request, with the request's key, and an import
+     *   into it is confidential (#2110): no file or page name is logged.
+     * - Importing the same takeout again leaves the store as the first import
+     *   did (operator, 2026-09-25), except that a page or a file deleted since
+     *   comes back (operator, 2026-10-30; #2171). The engine skips a file it
+     *   already took (fingerprints), but a page with a uuid and a file are read
+     *   again (`rechecks`): the uuid check below decides for a page, and for a
+     *   file whether the store still holds its bytes (`ownStoreFingerprints`, read once a run),
+     *   so one still held is `duplicate` and not put again (no second upload
+     *   record). On a first import the file door returns a file the store
+     *   already holds. A page whose uuid the store holds is `duplicate`: unchanged, or
+     *   changed since the download, and then the page here is kept. A uuid
+     *   used elsewhere on the site is `duplicate`, the page named only when
+     *   the user may view it. A title held by a DIFFERENT page lands beside
+     *   it as `Title (imported)`.
+     * - The original is the file itself: none is kept or cited (D11), as for `core.files`.
+     * - The run is recorded as one act, `store-import`, with counts only, and
+     *   kept as a report page in the store, sealed when the store is (operator,
+     *   2026-09-25 and 2026-10-30): see {@link keepRunReport}.
+     */
+    private privateStoreReceiver;
+    /** The takeout import's rule, unchanged (#1472): `account-security`, and only into the user's own container. */
+    private mayImportIntoOwnStore;
+    /** Where the private-store receiver writes, from configuration. */
+    private privateStoreSetup;
+    /**
+     * The user's own stores this context can write now (#2118): each store on
+     * disk and the default one, which a user on a new site has before they
+     * wrote anything; an encrypted one only while unlocked in this session.
+     * Making a store is its own door (#1414): an encrypted one needs keys.
+     */
+    private ownStoresWritable;
+    /**
+     * One page or file of a takeout into the store `info.target` (#2118, as
+     * #1472 did). A file through FileManager's `put`; a page after the files
+     * it links to, its links pointed at their ids here, through PageManager's
+     * save door. Nothing here logs a page's or a file's name (#1461, #2110).
+     */
+    private receiveTakeoutEntry;
+    /** A takeout's page into the store, as #1472 decided: see {@link privateStoreReceiver}. */
+    private saveTakeoutPage;
+    /**
+     * The run as one act (#1472's `store-import`): who, which store, and how
+     * each file went, as counts. Never a page's or a file's name (#1461); each
+     * file's own record is its door's (`asset-upload`, a sealed store's by id).
+     * The counts use the old door's keys, so whatever reads the event reads
+     * one shape.
+     */
+    private recordStoreImport;
     /**
      * Get available format IDs
      *
@@ -656,6 +903,22 @@ declare class ImportManager extends BaseManager {
         /** The uploaded file's name, for the report page. */
         sourceName?: string;
     }): Promise<TakeoutImportReport>;
+    /**
+     * An engine run into `core.private-store` as the takeout report the old
+     * door keeps (code review of #2160, finding 3; operator, 2026-10-30), from
+     * the run's per-file status. Only a run that read a takeout keeps one.
+     * A file the run skipped as already imported is in neither count.
+     *
+     * @returns How many files no page links to
+     */
+    private keepRunReport;
+    /**
+     * A takeout import's report, kept (operator, 2026-09-25): which files no
+     * page now in the store links to, counted in the log, and a page in the
+     * store it is about, sealed exactly when the store is, so it can name what
+     * a log may not. A failure to save it costs the record, never the import.
+     */
+    private keepTakeoutReport;
     /** The import report page's markdown. Private links are `[Title|store/Title]` (#1457). */
     private takeoutReportMarkdown;
     /**

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

@@ -105,6 +105,8 @@ declare class MediaManager extends BaseManager implements CatalogSource {
      * what degraded means (#1155) — configured, wanted, not working.
      */
     private recordFolderState;
+    /** One path per line, then "and N more" when the provider capped the list (#2191). */
+    private formatFileList;
     /**
      * Surface scan/rebuild anomalies to admins via /admin/notifications and the
      * server log (#807). Missing folders, capture-date gaps, and processing

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

@@ -120,6 +120,12 @@ export interface PageSaveOptions {
             from: string;
             to: string;
         } | null;
+        /**
+         * An import's file name, when the user gave the page another title
+         * (#2130): recorded on a `create` beside the title. Ignored for a private
+         * page, whose record names it by its vault name only.
+         */
+        importedFrom?: string;
         /**
          * Suppress the event. For writes that are a side effect of an already
          * audited operation, where a second record would describe the same act
@@ -908,6 +914,18 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * @throws PageAudienceRefusedError when the audience leaves `ctx` out
      */
     private assertAudienceAdmits;
+    /**
+     * The write door's shared-folder check (#2125): a folder's page is added,
+     * changed, moved or deleted only by a context the PDP permits
+     * `shared-folder-file` on its folder, whatever route it came by (the
+     * editor, the raw editor, the API, a restore). Reading a folder
+     * (`shared-folder-read`, which every admin holds on every folder) opens
+     * its key, so the store would take the write: this is what refuses it.
+     * A name that is not a folder page is not checked here.
+     *
+     * @throws when `ctx` may not file into the page's folder
+     */
+    private assertMayFileInSharedFolder;
     /**
      * Admin-override save (#689): the admin "Edit raw" textarea, split into
      * frontmatter and body and written through the door (#1462).
@@ -1081,6 +1099,9 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * or a share link the owner issued that names this vault. Anyone else gets
      * an empty list, the same as a vault with nothing in it. Whether each page
      * may then be read is still the page door's answer.
+     *
+     * A shared folder (`SHARED_FOLDER_OWNER`, #2125): whoever the PDP permits
+     * `shared-folder-read` on it.
      */
     listVaultPages(ctx: ActorContext, owner: string, vault: string): Promise<Array<{
         name: string;
@@ -1295,6 +1316,24 @@ declare class PageManager extends BaseManager implements CatalogSource {
         owner: string;
         store: string;
     }>>;
+    /**
+     * The pages of shared folders that match (#2125), from each folder's own
+     * sealed search index, as a private store's are found. Only the folders
+     * `ctx` may read: each is asked `shared-folder-read` here, whatever the
+     * caller passed, and a folder it may not read gives nothing, not even a
+     * count (decision 7). Folder pages are in no site-wide index.
+     *
+     * @param ctx - Who is searching (#1179)
+     * @param folders - The folders to search, by name (SharedFolderManager's list)
+     * @param ask - The query, as {@link matchStoreSearch} reads it
+     */
+    searchSharedFolderPages(ctx: ActorContext, folders: readonly string[], ask?: StoreSearchQuery): Promise<Array<StoreSearchMatch & {
+        name: string;
+        owner: string;
+        store: string;
+    }>>;
+    /** Matches from `owner`'s `stores`' own search indexes, read through `ctx`; a store that will not read gives none. */
+    private searchStoreIndexes;
     /**
      * Build a store's search index from its pages, replacing whatever is there.
      *
@@ -1361,6 +1400,20 @@ declare class PageManager extends BaseManager implements CatalogSource {
      * }
      */
     pageExists(identifier: string, ctx: ActorContext): boolean;
+    /**
+     * The uuid of the page that holds `name` as its title, or as its slug (#2140).
+     *
+     * Whether a name is taken — the uniqueness question a save and the shipped
+     * pages screen ask. An exact match, ignoring case, by the store's own rule
+     * (the provider's `uuidHoldingName`); never the plural or fuzzy matching
+     * `getPage` does for links, so "Reviews" is not held by "review".
+     *
+     * @param field - Which name: 'title' or 'slug'
+     * @param name - The title or slug
+     * @param ctx - Who is asking
+     * @returns The holder's uuid, or null when no page holds it
+     */
+    uuidHoldingName(field: 'title' | 'slug', name: string, ctx: ActorContext): string | null;
     /**
      * The private titles `ctx` can see in `owner`'s stores, by store id (#1457).
      *

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

@@ -222,6 +222,10 @@ declare class SearchManager extends BaseManager {
      * yields nothing rather than an error.
      *
      * A private row carries the page's private name, so `pageUrl` links to it.
+     *
+     * And the pages of the shared folders the requester may read (#2125), from
+     * each folder's own sealed index, through the same door. A folder they may
+     * not read gives nothing: no row, no title, no count (decision 7).
      */
     private mergeOwnPrivateResults;
     /**