@jwilleke/ngdpbase-types 5.40.0 → 5.41.1

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

@@ -14,9 +14,10 @@
  *   noise filter, fingerprints, skipping unchanged files, per-file status,
  *   keeping the original, and running the work as a background job.
  *
- * Only importing is built in the first slice. `out` / `both` shims and the
- * `write` half are declared so export (#1974) and feeds (D10) fit later
- * without changing these shapes.
+ * - An __export source__ is the owner's door for reading the thing being
+ *   exported (#2120): a page, later a search result or an add-on's list. It
+ *   checks the owner's existing read permission (D5) and yields items that
+ *   `out` shims chain into one file to download.
  */
 import type { ActorContext } from '../context/ActorContext.js';
 import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
@@ -61,6 +62,28 @@ export interface IceItem {
      * (a feed entry): an item whose key the engine has seen before is skipped.
      */
     itemKey?: string;
+    /**
+     * The archive the file was unpacked from (#2118), when it was: what lies
+     * beside it, for a shim whose format spans the files of an archive (a
+     * takeout's pages link to its files by the ids its file index names).
+     * The engine still hands each file to the shims on its own.
+     */
+    archive?: IceArchiveView;
+}
+/**
+ * The archive a file was unpacked from (#2118): this file's own path in it,
+ * and every member, read only. Paths are the archive's own, `/`-separated.
+ * Never part of an item's key: what an item is, is its content.
+ */
+export interface IceArchiveView {
+    /** The archive's name, as the file's `name` begins: `takeout.zip`. */
+    name: string;
+    /** This file's path within the archive. */
+    path: string;
+    /** Every member's path, in the archive's order. */
+    paths: readonly string[];
+    /** A member's bytes, or undefined when there is no such member. */
+    read(memberPath: string): Buffer | undefined;
 }
 /**
  * The `data` of a `record` item (#2109): one row of a table or one entry of a
@@ -99,6 +122,14 @@ export interface ShimTools {
      */
     options: Record<string, unknown>;
 }
+/** What an `out` shim is handed (#2120): a shim's tools, and who the export is for. */
+export interface ExportShimTools extends ShimTools {
+    /**
+     * The job context of the user who asked for the export, for a core shim
+     * that calls a core door with it (the PDF render, P1).
+     */
+    ctx: ActorContext;
+}
 /** What a shim's read returns. */
 export interface ShimReadResult {
     items: IceItem[];
@@ -107,6 +138,13 @@ export interface ShimReadResult {
      * records plus a partial note): the file's status is then `partial`, with this.
      */
     partial?: string;
+    /**
+     * Set, with no items, when the file is part of its format's layout and
+     * holds nothing to import on its own (#2118): a takeout's file index, read
+     * through the archive by the files it names. The file's status is then
+     * `noise`, with this, and the ledger records nothing for it.
+     */
+    skip?: string;
 }
 /**
  * A shim as its author writes it (D7). `name` is unique within its owner; the
@@ -132,8 +170,47 @@ export interface IceShim {
     duplicates?: 'file' | 'item';
     /** Inbound: read one input. Required for `in` and `both`. */
     read?(input: IceItem, tools: ShimTools): Promise<ShimReadResult>;
-    /** Outbound (export, #1974): not run in the first slice. Required for `out` and `both`. */
-    write?(items: IceItem[], tools: ShimTools): Promise<IceItem[]>;
+    /**
+     * Outbound (export, #2120): turn the items into this shim's `produces`.
+     * Required for `out` and `both`. An outbound shim matches its input by
+     * `accepts.kinds` alone; a shim that produces `file` makes the download,
+     * and is what the Export action offers.
+     */
+    write?(items: IceItem[], tools: ExportShimTools): Promise<IceItem[]>;
+    /**
+     * An outbound shim whose engine is missing says so (#2120): PDF with no
+     * provider chosen. The Export action does not offer it. Default: available.
+     */
+    isAvailable?(): boolean;
+    /**
+     * Vetting (#2149): clean this format's own kind of risky content out of a
+     * file that is about to be kept as a file (scripts and handlers in an SVG,
+     * HTML and formulas in CSV cells). Returns the cleaned bytes, and one note
+     * per kind of thing removed, saying what and how many, never the content.
+     * An inbound shim has `read()`, `clean()` or both; one with only `clean()`
+     * is never picked for a run.
+     */
+    clean?(input: IceItem): Promise<IceCleanResult>;
+}
+/** What a shim's `clean` returns (#2149). `removed` is empty when the file needed nothing. */
+export interface IceCleanResult {
+    bytes: Buffer;
+    removed: IceWarning[];
+}
+/**
+ * A file after the engine's vetting (#2149): its type read from its bytes,
+ * and, when its format's shim found something to clean, the cleaned bytes
+ * and what was removed. The caller keeps `bytes`, never the bytes it sent.
+ */
+export interface IceVetResult {
+    name: string;
+    bytes: Buffer;
+    /** From the bytes when they show it (#1624), else the declared or extension type. */
+    mediaType: string;
+    /** What cleaning removed, one note per kind; empty when nothing was. */
+    removed: IceWarning[];
+    /** The shim that cleaned it, when one did. */
+    cleanedBy?: string;
 }
 /** A shim the engine holds: its full id, and who registered it. */
 export interface RegisteredShim extends IceShim {
@@ -214,6 +291,18 @@ export interface ReceiveInfo {
      * taken there: never a silent replace.
      */
     givenName?: string;
+    /**
+     * The place within the receiver the run goes to (#2118), for a receiver
+     * with `targets`: one its `targets` gave the user the run is for, checked
+     * by the engine before the run. The receiver's door still checks it.
+     */
+    target?: string;
+    /**
+     * Set when the file was taken before and is read again only because the
+     * receiver `rechecks` this item (#2171): the receiver's own check decides
+     * whether it still holds it, and one it holds is `duplicate`.
+     */
+    rechecked?: boolean;
 }
 /** What a receiver's `fileDone` is told (#2109). */
 export interface FileDoneInfo extends ReceiveInfo {
@@ -236,6 +325,11 @@ export interface ReceiveOutcome {
      */
     heldAs?: string;
 }
+/** A place within a receiver (#2118): a user's private store. */
+export interface IceTarget {
+    id: string;
+    label?: string;
+}
 /**
  * A receiver as its owner writes it (D4). Its doors are the receiver's own
  * existing ones; each checks its own permission with the context given (D5).
@@ -294,6 +388,49 @@ export interface IceReceiver {
      * before the run is queued; the run reuses what was kept and needs no key.
      */
     keepsEncrypted?: boolean;
+    /**
+     * `receive` itself may write into an encrypted store (a takeout into a
+     * sealed private store, #2118), which only a request holding the user's
+     * unlocked key can write. The engine then runs an upload into it during
+     * the upload request, with the request's own context, instead of as a
+     * background job: no key is ever carried into a job (#2034's decision).
+     * An import into it is confidential (#2110). Core's only: an add-on
+     * receiver that declares it is refused at registration, so an add-on is
+     * confidential only through `keepsEncrypted`.
+     */
+    writesEncrypted?: boolean;
+    /**
+     * A zip inside an uploaded zip is handed on as a file, not unpacked
+     * (#2118): for a receiver whose format holds zips as content (a takeout's
+     * files). Without it, the engine unpacks nested zips too.
+     */
+    innerZipsAsFiles?: boolean;
+    /**
+     * The items this receiver checks for itself whether it still holds
+     * (#2118, operator 2026-10-30): a takeout's page, by its uuid, and a
+     * takeout's file, by its bytes (#2171), so one deleted since an earlier
+     * import comes back when the same takeout is imported again. A file whose
+     * fingerprint the scope already took is then read again, and only these
+     * of its items go to `receive`, with `info.rechecked`; the rest are
+     * duplicates. When nothing new is stored it stays `unchanged`, unrecorded,
+     * as the fingerprint skip leaves it. Without this, the fingerprint decides.
+     */
+    rechecks?(item: IceItem): boolean;
+    /**
+     * The places within this receiver this context may import into (#2118):
+     * a user's own private stores. The receiver's own rule (D5). A receiver
+     * with targets takes a run only with one of them (`IceRunRequest.target`),
+     * which the engine checks against this before the run, binds into the
+     * ledger scope, and hands on in every item's `ReceiveInfo.target`.
+     */
+    targets?(ctx: ActorContext): Promise<IceTarget[]>;
+    /**
+     * Called once when a run into this receiver has read every file (#2118),
+     * with its report: a receiver that records the run as one act (a
+     * takeout's `store-import` audit event). Not called for a refused run. A
+     * throw is the run's failure.
+     */
+    runDone?(ctx: ActorContext, report: IceRunReport): Promise<void>;
     /** The original-file choices this receiver offers (D11). Without it: all three. */
     originals?: IceOriginalChoices;
     /**
@@ -321,6 +458,8 @@ export interface IceUpload {
      * drops it on a zip). Checked by the engine against the receiver's `names`.
      */
     givenName?: string;
+    /** The archive the engine unpacked this file from (#2118); set by the engine, never by a caller. */
+    archive?: IceArchiveView;
 }
 /**
  * A URL the engine fetches as the run's one file (D1, D10, #2109): through
@@ -378,6 +517,12 @@ export interface IceRunRequest {
      * client sent.
      */
     options?: Record<string, unknown>;
+    /**
+     * The place within the receiver (#2118), for a receiver with `targets`:
+     * one of those it gives the user the run is for. Required for such a
+     * receiver and refused for any other.
+     */
+    target?: string;
 }
 /** Per-file status (first slice). */
 export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
@@ -410,6 +555,8 @@ export interface IceFileReport {
 export interface IceRunReport {
     runId: string;
     receiver: string;
+    /** The place within the receiver (#2118), when it has places. */
+    target?: string;
     scope: string;
     /** Who it ran as. */
     username: string;
@@ -461,6 +608,9 @@ export interface RecentImport {
     /** The receiver it went into. */
     receiver: string;
     receiverLabel?: string;
+    /** The place within it (#2118), when the receiver has places. */
+    target?: string;
+    targetLabel?: string;
     /** How many references the receiver gave (pages, records). */
     refs: number;
     /** Where the user can open the first of them (`linkFor`), when they may. */
@@ -482,3 +632,99 @@ export interface IceLedger {
     recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }
+/**
+ * The kind of the one item an export ends with: a file to download, with
+ * `bytes`, `mediaType` and the `name` it is saved under.
+ */
+export declare const EXPORT_FILE_KIND = "file";
+/** What an export source is told about the read it is asked for. */
+export interface ExportReadInfo {
+    /** The shim that will make the file (`core.pdf`). */
+    format: string;
+}
+/**
+ * The owner's door for reading the thing being exported (#2120, D5): a page
+ * through PageManager, later a search result or an add-on's list. Export
+ * starts from the thing (operator, 2026-10-28): the source says what kind of
+ * items it yields, and only the `out` shims that can make a file from that
+ * kind are offered.
+ */
+export interface IceExportSource {
+    name: string;
+    label?: string;
+    /** The kind of the items it yields, e.g. `ncm` for a page. */
+    yields: IceKind;
+    /**
+     * Would this context be allowed to export `ref`? Asked only to decide
+     * whether to offer the Export action: an affordance, which records nothing.
+     * The owner's existing read rule (D5).
+     */
+    mayExport(ref: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Read `ref` for export as `ctx`: the door. It checks the owner's existing
+     * permission, records what its owner records, and answers null when the
+     * thing is not there or `ctx` may not export it, without telling the two apart.
+     */
+    read(ref: string, ctx: ActorContext, info: ExportReadInfo): Promise<IceItem[] | null>;
+    /**
+     * Record how an export of `ref` ended, as its owner records exports: once
+     * the run has ended, with the file made or not. Also called, as a failure,
+     * when what was read is not exported (too large, the site too busy).
+     * Optional; a record that fails is logged, never thrown.
+     */
+    recordExport?(ref: string, ctx: ActorContext, outcome: ExportOutcome): Promise<void>;
+}
+/** How an export ended, for its source's record (#2120). */
+export interface ExportOutcome {
+    /** The shim that made, or was to make, the file. */
+    format: string;
+    runId: string;
+    /** The names of the items the source read. */
+    items: string[];
+    result: 'success' | 'failure';
+    /** Why it failed, as the user is told. */
+    reason?: string;
+}
+export interface RegisteredExportSource extends IceExportSource {
+    id: string;
+    owner: string;
+}
+/** A format the Export action offers: the shim that makes the file, and the shims before it. */
+export interface IceExportFormat {
+    /** The shim that makes the file, `core.pdf`. */
+    id: string;
+    label: string;
+    /** Every shim the export runs through, in order, ending with `id`. */
+    chain: string[];
+}
+/** One export, as a caller asks for it. */
+export interface IceExportRequest {
+    /** The export source's id, `core.pages`. */
+    source: string;
+    /** What to export, in the source's own terms: a page's name. */
+    ref: string;
+    /** The format: an id `exportFormatsFor` offered. */
+    format: string;
+}
+/** The file an export made, as its status shows it. */
+export interface IceExportFile {
+    name: string;
+    mediaType: string;
+    size: number;
+}
+export interface IceExportReport {
+    runId: string;
+    source: string;
+    ref: string;
+    format: string;
+    chain: string[];
+    /** Who it ran as: the only user who sees it or downloads its file. */
+    username: string;
+    state: 'queued' | 'running' | 'done' | 'failed';
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+    file?: IceExportFile;
+    /** When the file is let go (`ngdpbase.export.engine.keep-minutes`). */
+    expiresAt?: string;
+}

package/lib/src/ice/vet.d.ts

@@ -0,0 +1,19 @@
+import type { IceUpload, IceVetResult, RegisteredShim } from './types.js';
+/** A file whose format's shim failed while cleaning it: it is not kept, since it could not be checked. */
+export declare class IceVetRefused extends Error {
+    readonly file: string;
+    readonly reason: string;
+    constructor(file: string, reason: string);
+}
+/**
+ * The shim that cleans this file: one whose media types include the type the
+ * bytes show; or, when the bytes show no type of their own (CSV, plain text),
+ * one whose extensions include the file's. Its "can I read this?" must agree.
+ */
+export declare function cleanerFor(shims: readonly RegisteredShim[], name: string, mediaType: string, bytesShowType: boolean): RegisteredShim | null;
+/**
+ * Vet one file (#2149). `shims` are the enabled ones. Throws
+ * {@link IceVetRefused} when the cleaning shim fails: a file that could not
+ * be checked is not kept.
+ */
+export declare function vetFile(shims: readonly RegisteredShim[], upload: IceUpload): Promise<IceVetResult>;

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

@@ -6,12 +6,14 @@ import { type ActorContext } from '../context/ActorContext.js';
  * failed" (#1183). A caller refusing a destructive action needs to say which.
  */
 export declare const AUDIT_WRITE_FAILED = "EAUDITWRITE";
+import type { AttachmentDetail } from '../utils/auditEvents.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
 import type { User } from '../providers/BaseAttachmentProvider.js';
 import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
 import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import type { OriginalKeep } from '../ice/types.js';
+import type { FilePlace } from '../types/File.js';
 /**
  * Base attachment provider interface
  */
@@ -82,23 +84,24 @@ export interface FileInfo {
     mimeType: string;
     size: number;
 }
+/** A file handed to the write door (#2148): its bytes, and what the uploader said about them. */
+export interface PutFile {
+    bytes: Buffer;
+    info: FileInfo;
+}
 /**
- * Upload options interface
+ * What else a write carries (#2148). None of it decides where the file goes:
+ * that is the place the caller passed to `FileManager.put`.
  */
-export interface UploadOptions {
+export interface PutOptions {
+    /**
+     * The page that shows the file, recorded as a mention (and on the audit
+     * record of an unsealed place). Never the place: a page only links to a file.
+     */
     pageName?: string;
     description?: string;
     /** WikiContext for the current request — audit IP fallback */
     wikiContext?: import('../context/WikiContext.js').default;
-    /**
-     * Private-store destination (#1396): the upload dialog's checkbox. Decides
-     * only when `pageName` is not a private page — an upload onto a private page
-     * is always private, in that page's author's store (#1398). Absent or false
-     * otherwise keeps the public attachments pool.
-     */
-    private?: boolean;
-    /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
-    store?: string;
     /**
      * An import's keep at upload (#2061): the `OriginalKeep` the engine handed
      * the receiver's `keepOriginal`, passed on unchanged. Honoured only while
@@ -115,6 +118,31 @@ export interface UploadOptions {
      */
     importedFrom?: string;
 }
+/**
+ * The page-tied upload's options (#1396, #1398): today's callers name the page
+ * they upload onto and the dialog's Private tick, and FileManager turns that
+ * into a place (`placeForPageUpload`) until #2149/#2150 move them to a place
+ * the user chose.
+ */
+/**
+ * What storage hands back to FileManager (#2149): the stored file's metadata,
+ * and what the upload's audit record says about it, which FileManager records.
+ */
+export interface StoredInPlace {
+    metadata: AttachmentMetadata;
+    record: AttachmentDetail;
+}
+export interface UploadOptions extends PutOptions {
+    /**
+     * Private-store destination (#1396): the upload dialog's checkbox. Decides
+     * only when `pageName` is not a private page — an upload onto a private page
+     * is always private, in that page's author's store (#1398). Absent or false
+     * otherwise keeps the public attachments pool.
+     */
+    private?: boolean;
+    /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
+    store?: string;
+}
 /**
  * Mention object (WebPage reference)
  */
@@ -304,19 +332,39 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      */
     private writeAttachments;
     /**
-     * Upload an attachment
+     * Upload a file onto a page: the page-tied path its current callers use
+     * (the editor's upload route, imports, NCM image localization, thumbnails).
+     *
+     * #2148: this decides nothing. Where the file goes is FileManager's
+     * (`placeForPageUpload`, kept until #2149/#2150 move these callers to a
+     * place the user chose), and the write is FileManager's one door, `put`,
+     * which asks the permission for that place and then has this manager store
+     * it ({@link storeInPlace}). One write path, not two.
      *
-     * @param {Buffer} fileBuffer - File data
-     * @param {FileInfo} fileInfo - { originalName, mimeType, size }
-     * @param {UploadOptions} options - Upload options
-     * @param {string} options.pageName - Page uploaded onto (optional). A private page forces the upload private, into its author's store (#1398)
-     * @param {string} options.description - File description
-     * @param {boolean} options.private - Private-store destination for an upload with no private page (#1396)
-     * @param {string} options.store - Store id when private with no private page; else ConfigurationManager defaultstoreid
+     * @param fileBuffer - File data
+     * @param fileInfo - { originalName, mimeType, size }
      * @param ctx - Who is uploading (#1179): the request's subject, or a JobContext for an in-engine caller. Mandatory and positional.
-     * @returns {Promise<AttachmentMetadata>} Attachment metadata
+     * @param options - The page it is uploaded onto, the private tick and store, description, keep, importedFrom
+     * @returns Attachment metadata
      */
     uploadAttachment(fileBuffer: Buffer, fileInfo: FileInfo, ctx: ActorContext, options?: UploadOptions): Promise<AttachmentMetadata>;
+    /** The owner of files (#2148, #2149): every upload goes through its door, and it writes every upload and delete record. */
+    private fileManager;
+    /**
+     * Store a file in `place` (#2148): the storage underneath FileManager's
+     * door. Only `FileManager.put` calls this, after it has asked the
+     * permission for the place; nothing here decides where a file goes or who
+     * may put it there.
+     *
+     * What it does, as the place requires: the type read from the bytes
+     * (#1624); the uploader recorded by identity @id, and nobody uploads
+     * anonymously (#1926, #2097); a vault or shared folder keeps the file in its
+     * own store, sealed when the store is (#1460, #1394); and an import's kept
+     * original honoured only in its user's own vault (#2061). It records
+     * nothing (#2149): it returns what the upload's audit record says (a sealed
+     * store's file by id only, #2048), and FileManager, the owner, records it.
+     */
+    storeInPlace(ctx: ActorContext, place: FilePlace, file: PutFile, options?: PutOptions): Promise<StoredInPlace>;
     /**
      * The username an upload is recorded under (#1926): the person the context
      * names. Asked after policy has allowed the upload and before anything is
@@ -354,8 +402,12 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      */
     private userReference;
     private static uploaderOf;
-    /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
-    private assertMayEditPage;
+    /**
+     * A file is added to a private page only by someone who may edit it: the
+     * page's own decision (#1398). Asked here by `attachToPage`, and by
+     * FileManager's page-tied upload (#2148).
+     */
+    assertMayEditPage(ctx: ActorContext, pageName: string): Promise<void>;
     /**
      * One vault as a provider location, opened through `ctx` (#1842). Throws as
      * `storeFileIO` does: a locked vault, or a sealed kind's vault not yet opened.
@@ -428,9 +480,10 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
     /**
      * May `ctx` do `permission` to `what` in `owner`'s vault `store` (#1539)?
      * The container rule, then the capability asked with the vault, so
-     * `vault-owner` decides — the same rule as a vault page.
+     * `vault-owner` decides — the same rule as a vault page. FileManager's
+     * write door asks it for a vault (#2148), so the rule has one home.
      */
-    private mayInVault;
+    mayInVault(ctx: ActorContext, permission: string, owner: string, store: string, what: string): Promise<boolean>;
     /** The requester's own store file and its entry, before the capability is asked — see {@link findOwnStoreFile}. */
     private locateOwnStoreFile;
     /**
@@ -487,6 +540,15 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * differently without reading it twice (#1460).
      */
     isOwnPrivateStoreFile(attachmentId: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * The files the requester's own store `store` holds, as fingerprint → id,
+     * or null when this context cannot open it (#2171). The store's own
+     * duplicate check (its index's fingerprints), read without storing or
+     * recording anything: a takeout import reads it once per run and asks it
+     * before putting a file again, so a file deleted since comes back and one
+     * still held writes no second upload record. Only that store is opened.
+     */
+    ownStoreFingerprints(ctx: ActorContext, store: string): Promise<Map<string, string> | null>;
     /** The requester's own private-store files uploaded onto `pageName`. */
     getPrivateStoreAttachmentsForPage(pageName: string, ctx: ActorContext): Promise<AttachmentMetadata[]>;
     /**
@@ -839,18 +901,6 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
             ip?: string;
         } | null;
     }): Promise<boolean>;
-    /**
-     * Emit an attachment audit event from the manager that owns the resource.
-     *
-     * `docs/audit-posture.md` states the rule this implements: an action is
-     * "emitted through `recordAuditEvent` (or the manager door that calls it)".
-     * The door is here. Placing it at a route means every future caller has to
-     * remember, which is the thing #1120 exists to end — being audited must not
-     * depend on a producer recalling a method.
-     *
-     * `critical` decides whether a failure to record stops the action.
-     */
-    private recordAttachmentEvent;
     /** #1204: an attachment's metadata changed; field NAMES only, at the door both edit paths pass through. */
     private recordAssetEdit;
     /**