@jwilleke/ngdpbase-types 5.38.0 → 5.39.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -40,7 +40,7 @@ export type { PageAction } from '../../src/utils/pageUrl.js';
 export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
 export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as ImportManager } from '../../src/managers/ImportManager.js';
-export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceUrlSource, IceRunRequest, IceRecordData, FileDoneInfo, IceRunReport, IceFileReport, IceFileStatus, RecentImport } from '../../src/ice/types.js';
 export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
 export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';

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

@@ -25,6 +25,8 @@ declare abstract class ScopedLedger implements IceLedger {
     recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
     hasItem(scope: string, itemKey: string): Promise<boolean>;
     recordItem(scope: string, itemKey: string): Promise<void>;
+    seenItems(scope: string, itemKeys: string[]): Promise<Set<string>>;
+    recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }
 /** The ledger in memory: for tests, and for a site that keeps no import history. */

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

@@ -9,6 +9,8 @@ export interface IceEngineSettings {
     maxFileBytes: number;
     maxChainDepth: number;
     defaultOriginal: OriginalChoice;
+    /** The largest response a URL source may return (#2109). */
+    fetchMaxBytes: number;
 }
 export interface IceRunDeps {
     /** Enabled shims, in registration order. */
@@ -17,6 +19,8 @@ export interface IceRunDeps {
     ledger: IceLedger;
     settings: IceEngineSettings;
     tools(shim: RegisteredShim): ShimTools;
+    /** The engine's guarded fetch, for a URL source (#2109): the same one `tools` hands shims. */
+    fetch?: ShimTools['fetch'];
     now?: () => Date;
 }
 /** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
@@ -39,6 +43,8 @@ export declare const SCOPE_FORM = "ice2";
  * `sub` (phr's source id) narrows it within that user's scope, never outside.
  */
 export declare function boundScope(receiverId: string, owner: string, sub?: string): string;
+/** Does this shim list the receiver, by id or as any receiver (`'*'`, #2109)? */
+export declare function handsTo(shim: Pick<RegisteredShim, 'receivers'>, receiverId: string): boolean;
 export interface ChainLeaf {
     item: IceItem;
     chain: string[];

package/lib/src/ice/shims/csv.d.ts

@@ -0,0 +1,59 @@
+/**
+ * csv shim (#685 slice 4+, #911; a core shim since #2109) — zero dependency (a
+ * small RFC 4180 parser). Needed for sources that only publish CSV, e.g. NASA
+ * FIRMS thermal hotspots (geohazardwatch#4), whose `/api/area/csv/...`
+ * endpoint has no JSON/GeoJSON/XML variant.
+ *
+ * Nothing in it is about feeds, so any receiver of records can use it (a
+ * bank statement as well as a feed). The first row is the header; each
+ * subsequent row becomes one `record` item keyed by the header column names
+ * (all values are strings — `map`/dot-path and the downstream schema
+ * mappers cast as needed, exactly as for the other shims).
+ *
+ * Rows rarely carry an `id` column, so when neither the `recordIdField`
+ * option nor an `id` field resolves, a stable content hash of the row is
+ * synthesized as the id — order-independent (keys sorted) so a column
+ * reorder upstream doesn't churn ids, and content-addressed so
+ * change-detection still works.
+ *
+ * Delimiter defaults to `,`; override with the `delimiter` option (e.g. `\t`).
+ *
+ * The `skipLines` option skips N leading lines before the header (#1102).
+ * Some sources — government data exports especially — emit a human-readable
+ * caption above the real header. Without skipping it, the caption becomes
+ * the sole column name, the real header is consumed as the first record,
+ * and every column but the first is discarded. That failure is entirely
+ * silent: HTTP 200, a successful parse, records stored, and a table of empty
+ * values. Hence {@link preambleSuspicion}, which makes it visible (a warning
+ * on the read) without blocking it.
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/**
+ * Parse CSV text into header-keyed row objects. RFC 4180 subset: quoted fields,
+ * escaped quotes (`""`), embedded commas/newlines inside quotes, CRLF/CR/LF line
+ * endings, and a leading UTF-8 BOM. Values are returned verbatim (strings);
+ * header cells are trimmed. Fully-empty lines are skipped.
+ *
+ * `skipLines` drops that many leading lines before the header is taken, for
+ * feeds with a caption preamble (#1102). Default 0 — byte-identical to the
+ * previous behaviour.
+ */
+export declare function parseCsv(text: string, delimiter?: string, skipLines?: number): Record<string, string>[];
+/**
+ * Return the suspect header when a parse looks like it consumed an unskipped
+ * preamble, or `null` when it looks fine (#1102).
+ *
+ * The signature of the failure is a single column whose name reads like a
+ * sentence: a caption line has no delimiter in it, so the whole line becomes one
+ * field. A legitimate single-column CSV has a short, word-like header, so the
+ * two are distinguishable in practice.
+ *
+ * Deliberately advisory. A one-column CSV is legal, just unusual, and a caller
+ * that guessed and re-parsed would only trade a visible wrong answer for an
+ * invisible one.
+ */
+export declare function preambleSuspicion(columns: readonly string[]): string | null;
+/** One row as a record: its own id, or one synthesized from its content. */
+export declare function csvRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
+export declare const csvShim: IceShim;

package/lib/src/ice/shims/dotpath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Trivial dot-path lookup (#685) — the only "mapping engine" the framework has.
+ * NO JSONPath dependency (design §7): `getByPath(obj, 'properties.mag')`,
+ * `getByPath(obj, 'geometry.coordinates.2')` (numeric segment = array index).
+ * Returns undefined for any missing segment.
+ */
+export declare function getByPath(obj: unknown, path: string): unknown;

package/lib/src/ice/shims/geojson.d.ts

@@ -0,0 +1,19 @@
+/**
+ * GeoJSON shim (#685 slice 4; a core shim since #2109) — zero dependency (JSON.parse).
+ *
+ * Handles a GeoJSON FeatureCollection (`{ features: [...] }`), a bare array of
+ * features, or a single Feature. Per feature, the id comes from the
+ * `recordIdField` option (dot-path) or the feature's own `id`; properties come
+ * from the `map` option (dot-path per field) or, with no map, the feature's
+ * `properties` object.
+ *
+ * Reference feed: the USGS earthquakes GeoJSON
+ * (https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson).
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/** The features of a GeoJSON document. */
+export declare function geojsonFeatures(data: unknown): RawRecord[];
+/** One feature as a record. With no map, the feature's own `properties` object is lifted. */
+export declare function geojsonRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
+export declare const geojsonShim: IceShim;

package/lib/src/ice/shims/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Core's record shims (#2109; moved into core by the operator's decision of
+ * 2026-10-29, "generic work goes to core"): one per structured format,
+ * registered by ImportManager as `core.<name>`, so any receiver that takes
+ * records can use them, with no add-on enabled. The feeds add-on was their
+ * first user and names one per source as its `adapter`; accounting's bank
+ * statements (#2121) are the next.
+ *
+ * Shipped: geojson + rest-json (zero-dep), xml (fast-xml-parser), csv
+ * (zero-dep, #911), rss-atom (#913, xml-based) and xml-index (#912, two-phase).
+ * Each produces `record` items with per-item duplicates and hands to any
+ * receiver that takes records (`receivers: ['*']`).
+ */
+import type { IceShim } from '../types.js';
+/** Every record shim, in registration order. */
+export declare const RECORD_SHIMS: readonly IceShim[];

package/lib/src/ice/shims/record.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What core's record shims share (#685 slice 8; core shims since #2109): the
+ * options a run hands its shim, turning one raw item into a `record` item,
+ * and the item's key.
+ *
+ * Nothing here is about any one receiver. A record shim reads one format
+ * into `record` items (`data` is `{ id, properties }`, `IceRecordData`); which
+ * receiver takes them, and what it does with them, is the receiver's
+ * business. So the same CSV shim serves a feed (the feeds add-on's
+ * `feeds.items`) and a bank-statement import alike, with neither add-on's
+ * code (operator, 2026-10-29: generic work goes to core).
+ *
+ * id ← the `recordIdField` option (dot-path) or the item's own `id`.
+ * properties ← the `map` option (dot-path per field), or — with no map — the
+ * supplied `defaultProps` object (geojson lifts `feature.properties`;
+ * rest-json lifts the item itself). No id resolves → no record (skipped).
+ */
+import type { IceItem, IceRecordData, IceWarning } from '../types.js';
+/** One raw item straight off the wire (a GeoJSON feature, an RSS item, a CSV row, …). */
+export type RawRecord = Record<string, unknown>;
+/** The kind every record shim produces: core's generic record (#2109). */
+export declare const RECORD_KIND = "record";
+/**
+ * A record shim's options (#2109): the site's `ngdpbase.import.shims.<id>.options`,
+ * with the run's own over them (a feed source's settings, an import's).
+ * Each is optional and generic: where the items are, which field is the id,
+ * a field map, and the few format settings (CSV's delimiter and preamble, an
+ * index's links).
+ */
+export interface RecordShimOptions {
+    /** Dot-path to each item's id. */
+    recordIdField?: string;
+    /** Dot-path map: property → source path. */
+    map?: Record<string, string>;
+    /** Dot-path to the items array (rest-json, xml, rss-atom, xml-index). */
+    itemsPath?: string;
+    /** csv: the field delimiter. Default ','. */
+    delimiter?: string;
+    /** csv: lines skipped before the header (#1102). Default 0. */
+    skipLines?: number;
+    /** xml-index: a regex matched against the index's hrefs. */
+    linkPattern?: string;
+    /** xml-index: the most item documents fetched in one run. */
+    maxItems?: number;
+}
+/**
+ * The options as a shim reads them: each of the right type, or absent. The
+ * caller (a feed's configuration) validated its own; this only refuses a
+ * value of the wrong type from anywhere.
+ */
+export declare function recordOptions(raw: Record<string, unknown>): RecordShimOptions;
+export declare function buildRecord(raw: RawRecord, opts: RecordShimOptions, defaultProps: Record<string, unknown> | undefined): IceRecordData | null;
+/**
+ * The key the engine knows a record by (per-item duplicates, #2109): its own
+ * id with a hash of its content. The id alone would skip a record that
+ * changed upstream under the same id (a revised advisory), so the hash is
+ * the version. A receiver's own duplicate check is still its own (the feeds
+ * add-on compares the hash its record store keeps).
+ */
+export declare function recordItemKey(rec: IceRecordData): string;
+/** The `record` items of one read, from its records in order; null records (no id) are dropped. */
+export declare function recordItems(input: IceItem, records: Array<IceRecordData | null>, warnings?: IceWarning[]): IceItem[];
+/**
+ * Locate the items array in a JSON response when no explicit `itemsPath` is
+ * configured: the body itself if it's an array, else the first array found
+ * under common envelope keys, else any array-valued property, else [].
+ */
+export declare function pickItemsArray(data: unknown): unknown[];

package/lib/src/ice/shims/restjson.d.ts

@@ -0,0 +1,14 @@
+/**
+ * rest-json shim (#685 slice 8; a core shim since #2109) — zero dependency (JSON.parse).
+ *
+ * Generic REST GET → JSON. Locates the items array via the `itemsPath` option
+ * (dot-path, e.g. 'results' or 'data.events'); with none, falls back to the
+ * body itself if it's an array, or the first array under a common envelope
+ * key (results/data/items/records). Each item IS the record (its own fields
+ * are lifted as properties when no `map` is set).
+ */
+import { type IceShim } from '../types.js';
+import { type RawRecord } from './record.js';
+/** The items of a JSON document: at `itemsPath`, or the first likely array. */
+export declare function jsonItems(data: unknown, itemsPath: string | undefined): RawRecord[];
+export declare const restJsonShim: IceShim;

package/lib/src/ice/shims/rss-atom.d.ts

@@ -0,0 +1,22 @@
+/**
+ * rss-atom shim (#913; a core shim since #2109) — dependency: fast-xml-parser
+ * (shared with the xml shim). RSS 2.0 and Atom 1.0 are both XML, so this is a
+ * thin, sensible-default wrapper over the shared XML machinery rather than a
+ * separate parser.
+ *
+ * Item location (when the `itemsPath` option is not set):
+ *   - RSS 2.0 → `rss.channel.item`
+ *   - Atom 1.0 → `feed.entry`
+ *   - else the generic envelope detection (pickItemsArray)
+ *
+ * Id resolution (when `recordIdField` is not set): RSS `<guid>` → `<link>`;
+ * Atom `<id>` → `<link href>`. guid/link may parse as objects (guid with
+ * `@isPermaLink`, Atom link as an attribute-only element) — both are unwrapped.
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/** The items of an RSS or Atom document. */
+export declare function rssAtomItems(text: string, itemsPath: string | undefined): RawRecord[];
+/** One RSS item or Atom entry as a record. */
+export declare function rssAtomRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
+export declare const rssAtomShim: IceShim;

package/lib/src/ice/shims/xml-index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * xml-index shim (#912; a core shim since #2109) — dependency: fast-xml-parser
+ * (shared with the xml shim). For "index page + N item documents, no
+ * combined feed" sources common to bulletin-style publishers (e.g. Washington
+ * VAAC ash advisories, geohazardwatch#5): an HTML/text index links to many
+ * separately-fetchable per-record XML files, with no single URL returning
+ * them all.
+ *
+ * Two phases:
+ *   1. The index is the file the engine hands it (a URL source, fetched by the
+ *      engine). Item URLs are the hrefs matching the `linkPattern` option (a
+ *      regex string), resolved against the index's URL (`metadata.sourceUrl`,
+ *      else the file's name). Deduped, capped at the `maxItems` option
+ *      (default 100; a site sets its own with
+ *      `ngdpbase.import.shims.core.xml-index.options.maxItems`).
+ *   2. Each item document is fetched by asking the engine (`tools.fetch`), so
+ *      every request takes the one guarded path with the source's headers
+ *      and timeout (design rule), then XML-parsed. Each yields one record (its
+ *      unwrapped root), or — with `itemsPath` — the items located in it. The
+ *      item's URL is kept as `__itemUrl` so it serves as the id when the
+ *      document has none.
+ *
+ * A single failed item fetch or parse is skipped, never failing the whole
+ * read: the read is then `partial`, saying which.
+ */
+import { type IceShim } from '../types.js';
+import { buildRecord, type RecordShimOptions, type RawRecord } from './record.js';
+/** Extract, resolve, dedupe and cap item URLs from index HTML/text. */
+export declare function extractItemUrls(html: string, baseUrl: string, linkPattern: string, maxItems: number): string[];
+/** One item document's record: `__itemUrl` is plumbing, kept out of the properties but usable as the id. */
+export declare function xmlIndexRecord(raw: RawRecord, opts: RecordShimOptions): ReturnType<typeof buildRecord>;
+export declare const xmlIndexShim: IceShim;

package/lib/src/ice/shims/xml.d.ts

@@ -0,0 +1,30 @@
+/**
+ * xml shim (#685 slice 8; a core shim since #2109) — dependency: fast-xml-parser
+ * (itself zero-dep).
+ *
+ * Generic XML → records, for sources with no JSON surface (e.g. VAAC ash
+ * advisories, geohazardwatch#5). The document is parsed to plain objects so
+ * the existing dot-path machinery applies unchanged: locate the items array
+ * via the `itemsPath` option (e.g. 'rss.channel.item' or
+ * 'advisories.advisory'), map fields via `map` / `recordIdField`.
+ *
+ * XML-specific shape rules:
+ * - Attributes are kept, prefixed '@' — dot-path them as e.g. 'link.@href'.
+ * - Element text alongside attributes lands under '#text'.
+ * - A single repeated element parses as an object, not a 1-element array —
+ *   the shim coerces the located items to an array, so `itemsPath` behaves
+ *   identically for 1 and N items.
+ */
+import { XMLParser } from 'fast-xml-parser';
+import { type IceShim } from '../types.js';
+import { type RawRecord } from './record.js';
+/**
+ * Shared fast-xml-parser instance — reused by the rss-atom (#913) and xml-index
+ * (#912) shims so XML shape rules stay identical across all XML-based sources.
+ */
+export declare const xmlParser: XMLParser;
+/** XML parses a lone repeated element as an object — normalize to an array. */
+export declare function coerceItems(located: unknown): RawRecord[];
+/** The items of an XML document: at `itemsPath`, else under its (single) root by envelope detection. */
+export declare function xmlItems(text: string, itemsPath: string | undefined): RawRecord[];
+export declare const xmlShim: IceShim;

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

@@ -20,12 +20,16 @@
  */
 import type { ActorContext } from '../context/ActorContext.js';
 import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
+/** In a shim's `receivers`: any receiver that takes the kind the shim produces (#2109). */
+export declare const ANY_RECEIVER = "*";
 /** D3: which way a shim moves data. Most are `in`; PDF (#1974) would be `both`. */
 export type ShimDirection = 'in' | 'out' | 'both';
 /**
  * The kind of a piece of content moving through the engine. `file` is raw
- * input bytes; `html` and `ncm` are core's; an add-on's own kinds are named
- * `<slug>.<kind>`, e.g. `phr.health-record`.
+ * input bytes; `html` and `ncm` are core's; `record` is one structured entry
+ * of a table or feed (`data` is `{ id, properties }`, {@link IceRecordData}),
+ * so a format shim such as CSV serves any receiver that takes records (#2109);
+ * an add-on's own kinds are named `<slug>.<kind>`, e.g. `phr.health-record`.
  */
 export type IceKind = string;
 /** A structured note from a shim, the same shape as a converter's warning. */
@@ -57,6 +61,15 @@ export interface IceItem {
      */
     itemKey?: string;
 }
+/**
+ * The `data` of a `record` item (#2109): one row of a table or one entry of a
+ * feed. `id` is the entry's own id (a configured id field, the format's own
+ * id, or a hash of the row when it has none); `properties` its fields.
+ */
+export interface IceRecordData {
+    id: string;
+    properties: Record<string, unknown>;
+}
 /** What a shim takes. A file matches by extension or media type; a chained input by kind. */
 export interface ShimAccepts {
     /** Lower-case, with the dot: `['.xml']`. */
@@ -78,7 +91,11 @@ export interface ShimTools {
      * path, with the site's egress policy, User-Agent and timeout.
      */
     fetch(url: string, options?: Omit<GuardedFetchOptions, 'policy' | 'transport' | 'resolver'>): Promise<GuardedResponse>;
-    /** This shim's options from site configuration (D6): `ngdpbase.import.shims.<id>.options`. */
+    /**
+     * This shim's options from site configuration (D6):
+     * `ngdpbase.import.shims.<id>.options`, with the run's own `options` over
+     * them (a feed source's parse settings, #2109).
+     */
     options: Record<string, unknown>;
 }
 /** What a shim's read returns. */
@@ -104,7 +121,10 @@ export interface IceShim {
     produces: IceKind;
     /**
      * Receivers it may hand to directly (ids, `core.pages` or `<slug>.<name>`).
-     * Empty for a shim whose output only feeds another shim.
+     * Empty for a shim whose output only feeds another shim. {@link ANY_RECEIVER}
+     * (`'*'`): any receiver that takes the kind it produces — a generic format
+     * shim such as core's CSV, whose `record` items any add-on's receiver may
+     * take (#2109). Each receiver still decides with its own permission (D5).
      */
     receivers: string[];
     /** Two duplicate kinds (design rule): a whole file by fingerprint, or each item by `itemKey`. Default `file`. */
@@ -185,6 +205,13 @@ export interface ReceiveInfo {
     citation?: IceCitation;
     original?: KeptOriginal;
 }
+/** What a receiver's `fileDone` is told (#2109). */
+export interface FileDoneInfo extends ReceiveInfo {
+    /** What the source said about the file: a URL source's `metadata`. */
+    metadata: Record<string, unknown>;
+    /** Every item the file held, in order: those handed to `receive`, and those skipped as already seen. */
+    items: IceItem[];
+}
 /** A receiver's answer for one item. `refused` is its existing permission saying no (D5). */
 export interface ReceiveOutcome {
     status: 'stored' | 'duplicate' | 'refused';
@@ -211,6 +238,29 @@ export interface IceReceiver {
     mayUse(ctx: ActorContext): Promise<boolean>;
     /** Hand one item to the receiver's own door. */
     receive(item: IceItem, ctx: ActorContext, info: ReceiveInfo): Promise<ReceiveOutcome>;
+    /**
+     * Called once per file whose shims read it through (#2109), after each of
+     * its items was handed to `receive` or skipped as already seen, with every
+     * item the file held, in order. A receiver that holds a snapshot of a
+     * source (a feed's records) stores it here and drops what the source no
+     * longer holds: an item skipped as already seen is still in the source.
+     * Not called for a file that failed before its items were known. Returns a
+     * note for the file's status; a throw fails the file.
+     */
+    fileDone?(ctx: ActorContext, info: FileDoneInfo): Promise<string | void>;
+    /**
+     * `false`: this receiver is fed only by its owner's own sources (a feed's
+     * schedule, #2109). The import screen never offers it and an upload into
+     * it is refused. Default: it takes uploads.
+     */
+    uploads?: boolean;
+    /**
+     * Where this context can open what one of its references names (#2110),
+     * for "your recent imports" on the import screen: a URL, or null when
+     * the thing is gone or this context may not open it. The receiver decides
+     * with its own existing read rule (D5). Without it, nothing is linked.
+     */
+    linkFor?(ref: string, ctx: ActorContext): Promise<string | null>;
     /**
      * Keep the original file itself (D11: phr keeps originals in its own
      * store). Without this, `keep` hands the original to the files receiver.
@@ -241,13 +291,36 @@ export interface IceUpload {
     mediaType?: string;
 }
 /**
- * A source (D1). The first slice reads uploads; a URL fetched on a schedule
- * (D10, feeds) and a server folder join this union later.
+ * A URL the engine fetches as the run's one file (D1, D10, #2109): through
+ * the one guarded path (`guardedFetch`, #1139) with the site's egress policy
+ * and default User-Agent, and the source's own headers and timeout (#1959),
+ * which also apply to every follow-up fetch a shim asks of the engine during
+ * the run. A feed's schedule is its owner's job; the engine fetches when run.
+ */
+export interface IceUrlSource {
+    type: 'url';
+    url: string;
+    /** The name the fetched file gets in reports and the ledger. Default: the URL. */
+    name?: string;
+    /** Request headers for every fetch of the run (a `User-Agent` replaces the site default). */
+    headers?: Record<string, string>;
+    /** Each fetch's time limit, ms. Default `ngdpbase.fetch-timeout-ms`. */
+    timeoutMs?: number;
+    /**
+     * Facts the source states about the file, carried on it and on every item
+     * read from it (a feed source's id). The engine adds `sourceUrl`, the URL
+     * fetched, so a shim can resolve the file's relative links.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A source (D1): uploaded files, or a URL fetched when the run starts
+ * (#2109). A server folder joins this union later.
  */
 export type IceSource = {
     type: 'upload';
     files: IceUpload[];
-};
+} | IceUrlSource;
 /** One import, as a caller asks for it. */
 export interface IceRunRequest {
     source: IceSource;
@@ -267,6 +340,12 @@ export interface IceRunRequest {
      * value a client sent.
      */
     scope?: string;
+    /**
+     * Options for this run's shims, over the site's (`ShimTools.options`): a
+     * feed source's parse settings (#2109). Server-built; never a value a
+     * client sent.
+     */
+    options?: Record<string, unknown>;
 }
 /** Per-file status (first slice). */
 export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
@@ -318,6 +397,25 @@ export interface LedgerFileEntry {
     /** The original kept for this fingerprint, whatever became of the conversion (D11). */
     original?: LedgerOriginal;
 }
+/**
+ * One file in a user's recent imports (#2110), read from the ledger: what
+ * the import screen lists, so the list survives a restart. Only the user's
+ * own entries, from the receivers they may use.
+ */
+export interface RecentImport {
+    name: string;
+    status: IceFileStatus;
+    message?: string;
+    /** When the ledger last recorded this file, ISO. */
+    at: string;
+    /** The receiver it went into. */
+    receiver: string;
+    receiverLabel?: string;
+    /** How many references the receiver gave (pages, records). */
+    refs: number;
+    /** Where the user can open the first of them (`linkFor`), when they may. */
+    link?: string;
+}
 /**
  * Where the engine keeps fingerprints, per-file status and item keys, per
  * scope. One interface so a database table can replace the file store when
@@ -328,5 +426,9 @@ export interface IceLedger {
     recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
     hasItem(scope: string, itemKey: string): Promise<boolean>;
     recordItem(scope: string, itemKey: string): Promise<void>;
+    /** Which of these item keys the scope has seen: one read for a whole file's items (#2109). */
+    seenItems(scope: string, itemKeys: string[]): Promise<Set<string>>;
+    /** Record several item keys in one write (#2109). */
+    recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }

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

@@ -221,6 +221,15 @@ export declare function backupKeyNotSaved(fingerprint: string): string;
 export declare const ENV_KEYS_SAVED_KEY = "ngdpbase.backup.env-keys-saved";
 /** The title of the one notification per change of the `.env` key set (#1976). */
 export declare const ENV_KEYS_CHANGED_TITLE = "Save a copy of .env";
+/**
+ * The config key that records an admin's confirmation that the shared-folders
+ * key is saved off the server (#2124, epic #1775 decision 1): its fingerprint,
+ * recorded when they confirm a downloaded `.env` that holds it. A different
+ * key asks again.
+ */
+export declare const SHARED_FOLDERS_KEY_SAVED_KEY = "ngdpbase.backup.shared-folders-key-saved-fingerprint";
+/** The banner while no admin has confirmed a saved `.env` holding the current shared-folders key (#2124). */
+export declare function sharedFoldersKeyNotSaved(fingerprint: string): string;
 /** The banner while the instance `.env` sets other names than the ones an admin last confirmed saved (#1976): names only, never a value. */
 export declare function envKeysChanged(change: {
     added: readonly string[];
@@ -240,6 +249,8 @@ export interface EnvKeysInfo {
     removed: string[];
     /** The file holds this site's current backup key, so a saved copy is a saved key too. */
     holdsBackupKey: boolean;
+    /** The file holds this site's current shared-folders key (#2124), so a saved copy is a saved key too. */
+    holdsSharedFoldersKey: boolean;
 }
 /** What Admin → Backup shows about the backup key: never the key itself. */
 export interface BackupKeyInfo {
@@ -458,6 +469,12 @@ declare class BackupManager extends BaseManager {
     private checkInstanceEnvKeys;
     /** The instance `.env` key set as Admin → Backup shows it (#1976), or null when the site has no instance data folder or the file can't be read. Never a value. */
     envKeysInfo(): EnvKeysInfo | null;
+    /**
+     * The shared-folders key as Admin → Backup shows it (#2124): set or not,
+     * its fingerprint, and whether an admin confirmed a saved `.env` holding
+     * it. Never the key. Read at use, like the backup key.
+     */
+    sharedFoldersKeyInfo(): BackupKeyInfo;
     /** The backup key as Admin → Backup shows it: set or not, its fingerprint, and whether an admin confirmed it is saved. Never the key. */
     backupKeyInfo(): BackupKeyInfo;
     /**
@@ -483,8 +500,9 @@ declare class BackupManager extends BaseManager {
      * With `envFingerprint` (#1976) the admin confirms the whole `.env` is
      * saved, the one confirmation for both reminders: the names it sets are
      * recorded (`ngdpbase.backup.env-keys-saved`), and so is the backup key
-     * when the file holds it. Refused when the names changed since the page
-     * was loaded.
+     * when the file holds it, and the shared-folders key when it holds that
+     * (#2124, `ngdpbase.backup.shared-folders-key-saved-fingerprint`). Refused
+     * when the names changed since the page was loaded.
      */
     confirmBackupKeySaved(ctx: ActorContext, fingerprint: string, envFingerprint?: string): Promise<void>;
     private configManager;

package/lib/src/managers/BackupManager.js

@@ -12,6 +12,7 @@ import { applyPartAtStart, beginSiteRestore, commitSiteRestore, discardSiteResto
 import { encryptBuffer, ENCRYPTED_SUFFIX } from '../utils/backupCrypto.js';
 import { readBackupDocument, verifyBackupOffThread } from '../utils/backupDocument.js';
 import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, isLeftOutForNoKey, LEFT_OUT_FOR_NO_KEY } from '../utils/backupKey.js';
+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';
@@ -195,8 +196,20 @@ export function backupKeyNotSaved(fingerprint) {
 export const ENV_KEYS_SAVED_KEY = 'ngdpbase.backup.env-keys-saved';
 /** The title of the one notification per change of the `.env` key set (#1976). */
 export const ENV_KEYS_CHANGED_TITLE = 'Save a copy of .env';
+/**
+ * The config key that records an admin's confirmation that the shared-folders
+ * key is saved off the server (#2124, epic #1775 decision 1): its fingerprint,
+ * recorded when they confirm a downloaded `.env` that holds it. A different
+ * key asks again.
+ */
+export const SHARED_FOLDERS_KEY_SAVED_KEY = 'ngdpbase.backup.shared-folders-key-saved-fingerprint';
 const ENV_KEYS_CHANGED_PREFIX = 'The keys in .env changed since an admin last saved it';
 const KEY_NOT_SAVED_PREFIX = 'Save the backup key off this server';
+const SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX = 'Save .env off this server: it holds the shared-folders key';
+/** The banner while no admin has confirmed a saved `.env` holding the current shared-folders key (#2124). */
+export function sharedFoldersKeyNotSaved(fingerprint) {
+    return `${SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX} (${SHARED_FOLDERS_KEY_ENV}, fingerprint ${fingerprint}), which opens every shared folder. Download .env on Admin → Backup and keep the copy off this server. This stays until an admin confirms it is saved`;
+}
 /** The banner while the instance `.env` sets other names than the ones an admin last confirmed saved (#1976): names only, never a value. */
 export function envKeysChanged(change) {
     const parts = [
@@ -779,15 +792,18 @@ class BackupManager extends BaseManager {
             // #1876: the banner asking an admin to save the key off the server, until one confirms;
             // then #1976's, while the .env key set differs from the one last confirmed. One at a time,
             // and one confirmation ("I have saved .env", which holds the key) can clear both.
-            const reminder = this.backupKeyInfo().saved ? envReminder : backupKeyNotSaved(backupKeyFingerprint(key));
+            // #2124: then the shared-folders key's, while no saved .env holding the current one is confirmed.
+            const shared = this.sharedFoldersKeyInfo();
+            const sharedReminder = shared.set && !shared.saved && shared.fingerprint ? sharedFoldersKeyNotSaved(shared.fingerprint) : null;
+            const reminder = this.backupKeyInfo().saved ? (envReminder ?? sharedReminder) : backupKeyNotSaved(backupKeyFingerprint(key));
             const status = this.getManagerStatus();
-            const ours = status.state === 'degraded' && (status.reason?.startsWith(KEY_NOT_SAVED_PREFIX) || status.reason?.startsWith(ENV_KEYS_CHANGED_PREFIX));
+            const ours = status.state === 'degraded' && [KEY_NOT_SAVED_PREFIX, ENV_KEYS_CHANGED_PREFIX, SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX].some((p) => status.reason?.startsWith(p));
             if (!reminder) {
                 if (ours)
                     this.markReady();
             }
             else if (status.state !== 'degraded' || ours) {
-                this.markNeedsAttention(reminder, reminder === envReminder ? ENV_KEYS_SAVED_KEY : BACKUP_KEY_SAVED_KEY);
+                this.markNeedsAttention(reminder, reminder === envReminder ? ENV_KEYS_SAVED_KEY : reminder === sharedReminder ? SHARED_FOLDERS_KEY_SAVED_KEY : BACKUP_KEY_SAVED_KEY);
             }
             return;
         }
@@ -876,9 +892,22 @@ class BackupManager extends BaseManager {
             recorded: recorded !== null,
             added: recorded ? names.filter((n) => !recorded.includes(n)) : [],
             removed: recorded ? recorded.filter((n) => !names.includes(n)) : [],
-            holdsBackupKey: Boolean(key) && readEnvLine(content, BACKUP_KEY_ENV) === key
+            holdsBackupKey: Boolean(key) && readEnvLine(content, BACKUP_KEY_ENV) === key,
+            holdsSharedFoldersKey: Boolean(currentSharedFoldersKey()) && readEnvLine(content, SHARED_FOLDERS_KEY_ENV) === currentSharedFoldersKey()
         };
     }
+    /**
+     * The shared-folders key as Admin → Backup shows it (#2124): set or not,
+     * its fingerprint, and whether an admin confirmed a saved `.env` holding
+     * it. Never the key. Read at use, like the backup key.
+     */
+    sharedFoldersKeyInfo() {
+        const key = currentSharedFoldersKey();
+        if (!key)
+            return { set: false, fingerprint: null, saved: false };
+        const fingerprint = sharedFoldersKeyFingerprint(key);
+        return { set: true, fingerprint, saved: this.setting(SHARED_FOLDERS_KEY_SAVED_KEY, '') === fingerprint };
+    }
     /** The backup key as Admin → Backup shows it: set or not, its fingerprint, and whether an admin confirmed it is saved. Never the key. */
     backupKeyInfo() {
         const key = currentBackupKey();
@@ -930,8 +959,9 @@ class BackupManager extends BaseManager {
      * With `envFingerprint` (#1976) the admin confirms the whole `.env` is
      * saved, the one confirmation for both reminders: the names it sets are
      * recorded (`ngdpbase.backup.env-keys-saved`), and so is the backup key
-     * when the file holds it. Refused when the names changed since the page
-     * was loaded.
+     * when the file holds it, and the shared-folders key when it holds that
+     * (#2124, `ngdpbase.backup.shared-folders-key-saved-fingerprint`). Refused
+     * when the names changed since the page was loaded.
      */
     async confirmBackupKeySaved(ctx, fingerprint, envFingerprint) {
         const STALE_KEY = 'That is not the fingerprint of the current backup key; reload Admin → Backup and check the key you saved';
@@ -950,6 +980,9 @@ class BackupManager extends BaseManager {
             await configManager.setProperty(BACKUP_KEY_SAVED_KEY, fingerprint, ctx);
         if (env)
             await configManager.setProperty(ENV_KEYS_SAVED_KEY, env.names, ctx);
+        const shared = this.sharedFoldersKeyInfo();
+        if (env?.holdsSharedFoldersKey && shared.fingerprint && !shared.saved)
+            await configManager.setProperty(SHARED_FOLDERS_KEY_SAVED_KEY, shared.fingerprint, ctx);
         await this.checkBackupKey();
     }
     // ---------------------------------------------------------------------------

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

@@ -10,6 +10,13 @@
  *   (`ngdpbase.consent.documents`, asked at sign-up and at an interactive
  *   sign-in) and each add-on's (asked before its per-person switch turns on,
  *   and again on a version change when the person next uses it).
+ * - __The recovery words (#1928).__ A user's confirmation that they saved
+ *   their recovery words (`RECOVERY_WORDS_CONSENT_SCOPE`), bound to the set
+ *   of words it is about (`subject`): asked where the words are shown, and
+ *   reminded by a banner — it never holds a session. An admin's confirmation
+ *   that they saved the organization's shared-folders recovery words
+ *   (`SHARED_FOLDERS_WORDS_CONSENT_SCOPE`, #2124) is the same kind of consent,
+ *   bound to the organization's set of words.
  *
  * The documents themselves are pages, read when asked (`version:` and
  * `effective:` front matter), never copied. Whether a person has accepted
@@ -93,8 +100,12 @@ declare class ConsentManager extends BaseManager {
      * The documents of `scope` that `username` has not accepted at their
      * current version — what they are to be asked. Empty when there is
      * nothing to ask (no documents, or no consent folder).
+     *
+     * In a scope bound to a subject (#1928, the recovery words) only an
+     * acceptance about `subject` counts, and with no subject there is nothing
+     * to ask: a user with no recovery words has none to confirm.
      */
-    pendingFor(username: string, scope?: ConsentScope): Promise<ConsentDocument[]>;
+    pendingFor(username: string, scope?: ConsentScope, subject?: string): Promise<ConsentDocument[]>;
     /**
      * "Your consents" for the person `ctx` acts as: each document of core's and
      * of each registered add-on, with their acceptance of the current version
@@ -114,10 +125,15 @@ declare class ConsentManager extends BaseManager {
      * - Each acceptance is recorded as `consent-grant` (on-failure refuse)
      *   before it is stored: a failed audit record refuses the acceptance.
      *
-     * @param how How they were asked: `sign-up`, `sign-in` or `add-on`
+     * - In a scope bound to a subject (#1928) the acceptance is about `subject`
+     *   (which set of recovery words); it is required there.
+     *
+     * @param how How they were asked: `sign-up`, `sign-in` or `add-on`; for the
+     *   recovery words `store-door`, `reminder` or `new-words`
+     * @param subject What the acceptance is about, in a scope bound to one
      * @returns The records written; empty when there was nothing to accept
      */
-    accept(ctx: ActorContext, scope: ConsentScope, seen: ConsentSeen[], how: string): Promise<ConsentRecord[]>;
+    accept(ctx: ActorContext, scope: ConsentScope, seen: ConsentSeen[], how: string, subject?: string): Promise<ConsentRecord[]>;
     /**
      * The account `username` was deleted (`AuthManager.closeAccess`): its
      * records go with it, after `consent-withdraw` names what it had accepted

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

@@ -32,7 +32,7 @@ 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, RegisteredShim } from '../ice/types.js';
+import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RecentImport, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
  */
@@ -380,6 +380,28 @@ declare class ImportManager extends BaseManager {
     getImportRun(runId: string, ctx: ActorContext): IceRunReport | null;
     /** The runs this process holds for the user `ctx` names, newest first (#2021): their own, never anyone else's. */
     importRunsFor(ctx: ActorContext): IceRunReport[];
+    /**
+     * The user's own recent imports, file by file, read from the ledger
+     * (#2110), so the list survives a restart: newest first, across the
+     * receivers `ctx` may use, at most `ngdpbase.import.engine.recent-imports`.
+     * Only the scopes bound to this user's identity (#2013), never anyone
+     * else's; a caller's narrower scope (phr's source id) is not read. Each
+     * entry links to what it created when the receiver says this user may
+     * open it (`linkFor`). Nothing is stored for this.
+     *
+     * @throws IdentityStoreUnavailableError when the identity store cannot
+     *   answer: whose entries they are cannot be told, so none is shown
+     */
+    recentImportsFor(ctx: ActorContext): Promise<RecentImport[]>;
+    /**
+     * 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
+     * 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.
+     */
+    isConfidential(receiverId: string): boolean;
     /** Use this ledger instead of the file one: a test's, or a database table's. */
     setImportLedger(ledger: IceLedger): void;
     /**
@@ -394,6 +416,13 @@ declare class ImportManager extends BaseManager {
      *   land in a scope the user's other runs do not use
      */
     private importScope;
+    /**
+     * Whose a scope is (#2013): the identity `@id` of the user `ctx` names, or
+     * their username when the identity store answers that they have none.
+     *
+     * @throws IdentityStoreUnavailableError when the store cannot answer
+     */
+    private scopeOwner;
     private newRunReport;
     private executeRun;
     /** What a run, or keeping at upload, works with. */
@@ -414,6 +443,12 @@ declare class ImportManager extends BaseManager {
     private ledger;
     /** What a shim is handed: the engine's guarded fetch (design rule) and its own options (D6). */
     private shimTools;
+    /**
+     * The engine's one way out (design rule, #1139): `guardedFetch` with the
+     * site's egress policy, read per call, and its default timeout. A URL
+     * source and every shim's follow-up fetch go through here (#2109).
+     */
+    private engineFetch;
     /** A receiver's existing permission, asked of the PDP with the run's context (D5, P2). */
     private permits;
     /**

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

@@ -253,6 +253,17 @@ export type VaultRepairResult = ({
     message: string;
 };
 /** The move of existing captures into the capture vault (#1505), recorded per vault it moved them out of. */
+/** The refusal when someone without `admin-system` names a system-category (#1503, operator 2026-10-29). */
+export declare const SYSTEM_CATEGORY_ADMIN_ONLY = "Only administrators can set a page's system category";
+/** What a write may give a page as its system-category ({@link PageManager.systemCategoryForWrite}). */
+export type SystemCategoryForWrite = {
+    ok: true;
+    category: string | undefined;
+    admin: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
 export declare const CAPTURE_VAULT_MIGRATION = "capture-vault";
 /** The move of private pages from the default vault into their system-category's own vault (#1507). */
 export declare const CATEGORY_VAULT_MIGRATION = "category-vaults";
@@ -429,6 +440,8 @@ declare class PageManager extends BaseManager implements CatalogSource {
      */
     private formerTitleIndex;
     private providerClass?;
+    /** The system-categories each shipped source ships, read once ({@link shippedSystemCategories}, #1503). */
+    private shippedCategoriesRead;
     /**
      * Creates a new PageManager instance
      *
@@ -583,9 +596,48 @@ declare class PageManager extends BaseManager implements CatalogSource {
     private loadSeededRecord;
     /**
      * The source for the required pages this release ships (#1405, #1406).
-     * Pages in a category whose source is `repo` are excluded.
+     * Pages in a system-category with no `storageLocation` (never stored on the
+     * site, #1503) are excluded.
      */
     requiredPagesSource(): ShippedPageSource;
+    /**
+     * The system-categories that ship pages (#1503), lower-cased: the
+     * `system-category:` values in the frontmatter of required-pages/ (read
+     * once) and of each enabled add-on's pages (read once per add-on; a page
+     * without one is `addon`, as the seed stamps it). No setting names them
+     * (operator, 2026-09-28). A file the seed would exclude is left out.
+     *
+     * Only for category questions (moving a page into one, the #1377 check):
+     * whether a page is shipped is {@link isShippedPageCopy}, per page.
+     */
+    shippedSystemCategories(): Promise<Set<string>>;
+    /** One shipped source's system-categories, read once; a failed read is not kept, so the next call reads again. */
+    private categoriesShippedBy;
+    private readShippedSystemCategories;
+    /**
+     * Which system-category a write by `ctx` gives a page (#1503, operator
+     * 2026-10-29): only an administrator (`admin-system`, asked of the PDP) sets
+     * or changes one. Anyone else's new page takes `fallback` (else the default
+     * system-category) and an existing page keeps its own (`current`); a request
+     * naming any other is refused, never rewritten. An administrator's request
+     * comes back as given (`undefined` when it names none), for the caller's own
+     * validation. Every write path that takes a system-category from a request
+     * asks here: create, save, ingest, takeout import.
+     *
+     * @param ctx - Who is writing
+     * @param requested - The system-category the request names, if any
+     * @param current - The page's system-category now; absent for a new page
+     * @param fallback - A new page's system-category when not the default (a vault's own)
+     */
+    systemCategoryForWrite(ctx: ActorContext, requested: unknown, current?: string | null, fallback?: string): Promise<SystemCategoryForWrite>;
+    /**
+     * Whether a page on the site is a shipped page (#1503): a copy of a shipped
+     * original, its uuid in the site's seeded-pages record, from required-pages/
+     * or an add-on's pages alike (operator, 2026-10-29). Decided per page, so a
+     * page someone creates on the site in a shipped system-category is not
+     * taken for a shipped one. Shipped pages are admin-only and never private.
+     */
+    isShippedPageCopy(uuid: string): Promise<boolean>;
     /**
      * One-time access backfill for a live required page (#1411): a page with no
      * `access` gets the default for its category, as a metadata-only save that
@@ -1654,8 +1706,6 @@ declare class PageManager extends BaseManager implements CatalogSource {
     private roleNames;
     /** Whether an index entry still holds an author or editor the conversion would change (#2097). No lookup is written. */
     private authorshipNeedsConversion;
-    /** The system-categories whose pages are shipped with the code (source `shipped`), lower-cased (#2097). */
-    private shippedCategories;
     /** `ngdpbase.page.authorship-conversion.batch-size`: pages converted between yields (#2097). */
     private authorshipBatchSize;
     /** Counts only, never a name (#2097): the log, and the dashboard for orphans and refused pages. */

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

@@ -57,6 +57,33 @@ export default class ShareManager extends BaseManager {
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
     isEnabled(): boolean;
+    /**
+     * The origin every share link is minted and shown with, no trailing slash.
+     *
+     * `ngdpbase.share.public-base-url` when it is set and valid: an instance
+     * whose own address is private (a LAN name) can hand out links that open
+     * from outside, through a tunnel or proxy that carries only `/share/…`.
+     * Otherwise the configured `ngdpbase.application.base-url`, else the
+     * request's own origin. Read on every call, so a change made on the admin
+     * screen applies to the next link shown.
+     */
+    linkBaseUrl(requestOrigin: string): string;
+    /**
+     * The one startup warning for a public origin on an instance that terminates
+     * TLS itself (#2117), or null. A plain-http connection to such an instance
+     * gets the #1163 redirect to `ngdpbase.application.base-url`, so a tunnel or
+     * proxy in front that connects over http sends every link's visitor to the
+     * site's own (possibly private) address. Whether a proxy exists, and how it
+     * connects, cannot be seen from here; the warning says what it must do.
+     */
+    publicOriginTlsWarning(nativeTls: boolean): string | null;
+    /**
+     * `ngdpbase.share.public-base-url`, validated: an absolute http(s) URL with
+     * no path beyond `/`, no query, fragment or credentials. Unset is
+     * `{ url: null, problem: null }`; an invalid value is ignored and named in
+     * `problem`.
+     */
+    private readPublicBaseUrl;
     /**
      * Issue a new share: a delegation by `issuer` of `actions` over `resources`
      * (#1221, epic #1225).

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

@@ -36,22 +36,28 @@ export interface PageValidationResult extends MetadataValidationResult {
 export interface ContentValidationResult {
     warnings: string[];
 }
-/**
- * Where a category's pages come from (#1503): made on this site, shipped with
- * the release in required-pages/, or kept in the repository's docs/ and never
- * stored on the site. Replaces the old storageLocation words one for one
- * (regular → site, required → shipped, github → repo).
- */
 /** A new share link's maximum lifetime when a vault's system-category sets none (operator, 2026-09-30, #1388). */
 export declare const DEFAULT_SHARE_MAX_DAYS = 15;
-export type CategorySource = 'site' | 'shipped' | 'repo';
 /**
- * A category entry's source. An entry without a valid one is a site category.
- * The one rule every reader of a category's source goes through.
+ * Where a system-category's pages are stored on the site (#1503,
+ * docs/system-category.md "Where a page's master copy lives"):
+ *
+ * - `none`: the entry has no `storageLocation`; its pages are never stored on
+ *   the site (they live in the repository's docs/), so saving one is refused
+ *   and none is seeded.
+ * - `public`: a `storageLocation` without a vault; its pages can never be
+ *   private.
+ * - `vault`: a `storageLocation.privatestore`; its pages may be private.
+ */
+export type CategoryStored = 'none' | 'public' | 'vault';
+/**
+ * Where an entry's pages are stored. The one rule every reader of "is this
+ * system-category stored here, and can it be private" goes through. A
+ * system-category's former `source` field is never read (#1503).
  */
-export declare function categorySource(cfg: {
-    source?: string;
-} | null | undefined): CategorySource;
+export declare function categoryStored(cfg: {
+    storageLocation?: unknown;
+} | null | undefined): CategoryStored;
 /**
  * What is wrong with a `ngdpbase.system-category` map, one line per problem
  * (#1504). Empty when it is sound. Startup refuses a map with problems
@@ -73,9 +79,13 @@ export interface CategoryConfig {
     label: string;
     description?: string;
     default?: boolean;
-    source?: CategorySource;
     enabled?: boolean;
     key?: string;
+    /** Where its pages are stored; see {@link categoryStored}. */
+    storageLocation?: {
+        defaultstore?: string;
+        privatestore?: string;
+    };
     /** `false`: its pages show no Comments tab and take no comment, unless a page says otherwise (#1951). */
     comments?: boolean;
     /** `false`: its pages show no Footnotes tab and take no footnote change, unless a page says otherwise (#1951). */
@@ -243,11 +253,12 @@ declare class ValidationManager extends BaseManager {
      */
     getCategoryConfig(label: string): CategoryConfig | null;
     /**
-     * Where a category's pages come from (#1503)
+     * Where a system-category's pages are stored on the site (#1503): see
+     * {@link categoryStored}. Null for a system-category the site does not
+     * know; no rule refuses a page for that.
      * @param {string} category - Category label
-     * @returns {CategorySource} 'site', 'shipped' or 'repo'; an unknown category is 'site'
      */
-    getCategorySource(category: string): CategorySource;
+    getCategoryStored(category: string): CategoryStored | null;
     /**
      * How a new page's Private box starts for this system-category and this
      * person (#1504): the entry's `defaultPrivate` — `true`, `false`, or

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

@@ -8,6 +8,37 @@ export type ConsentScope = string;
 export declare const CONSENT_PATH = "/consent";
 /** The scope of core's own documents, `ngdpbase.consent.documents`. */
 export declare const CORE_CONSENT_SCOPE = "core";
+/**
+ * The scope of a user's confirmation that they saved their own recovery words
+ * (#1928). Not core's terms: it never holds a session. It is asked where the
+ * words are shown (the store door, and a new set of words, #1925), and a user
+ * with encrypted vaults who has not confirmed the current version for their
+ * current words is reminded by a banner.
+ *
+ * Bound to a subject: the set of words (`recoveryWordsId`), so a new set asks
+ * again.
+ */
+export declare const RECOVERY_WORDS_CONSENT_SCOPE = "recovery-words";
+/** The page whose `version:` is the version of the recovery-words wording (#1928). */
+export declare const RECOVERY_WORDS_DOCUMENT = "recovery-words";
+/**
+ * The scope of an admin's confirmation that they saved the organization's
+ * shared-folders recovery words (#2124, epic #1775 decision 4). Like
+ * `recovery-words` it never holds a session: it is asked where the words are
+ * shown (Admin → Backup), and until the admin who was shown them confirms,
+ * holders of `admin-system` see a banner. Bound to a subject: the
+ * organization's set of words (`SharedFolderManager.recoveryWordsInfo().wordsId`),
+ * so a new set asks again.
+ */
+export declare const SHARED_FOLDERS_WORDS_CONSENT_SCOPE = "shared-folders-recovery-words";
+/** The page whose `version:` is the version of the shared-folders recovery-words wording (#2124). */
+export declare const SHARED_FOLDERS_WORDS_DOCUMENT = "shared-folders-recovery-words";
+/** Core's scopes bound to a subject, each with its one document (#1928, #2124). */
+export declare const SUBJECT_CONSENT_DOCUMENTS: Readonly<Record<ConsentScope, string>>;
+/** Scopes whose acceptance is about one thing (a subject), not the account as a whole (#1928). */
+export declare const SUBJECT_CONSENT_SCOPES: readonly ConsentScope[];
+/** Scopes core reserves: an add-on can never register one as its slug. */
+export declare const RESERVED_CONSENT_SCOPES: readonly ConsentScope[];
 /**
  * A document a person is asked to accept, as it stands now: a page whose
  * front matter carries `version:` and `effective:`. Read from the page each
@@ -46,7 +77,18 @@ export interface ConsentRecord {
      * account that takes the same username never inherits it.
      */
     account?: string;
-    /** Who and how: the account, where from, and the way they were asked (`sign-up`, `sign-in`, `add-on`). */
+    /**
+     * What the acceptance is about, in a scope bound to a subject (#1928): for
+     * the recovery words, which set of words (`recoveryWordsId`). Absent
+     * elsewhere. A new subject (a new set of words) asks again.
+     */
+    subject?: string;
+    /**
+     * Who and how: the account, where from, and the way they were asked
+     * (`sign-up`, `sign-in`, `add-on`; for the recovery words `store-door`,
+     * `reminder`, and `new-words` once #1925 makes a new set; for the
+     * shared-folders words `setup` and `reminder`).
+     */
     context: {
         by: string;
         how: string;

package/lib/src/types/Consent.js

@@ -6,6 +6,40 @@
 export const CONSENT_PATH = '/consent';
 /** The scope of core's own documents, `ngdpbase.consent.documents`. */
 export const CORE_CONSENT_SCOPE = 'core';
+/**
+ * The scope of a user's confirmation that they saved their own recovery words
+ * (#1928). Not core's terms: it never holds a session. It is asked where the
+ * words are shown (the store door, and a new set of words, #1925), and a user
+ * with encrypted vaults who has not confirmed the current version for their
+ * current words is reminded by a banner.
+ *
+ * Bound to a subject: the set of words (`recoveryWordsId`), so a new set asks
+ * again.
+ */
+export const RECOVERY_WORDS_CONSENT_SCOPE = 'recovery-words';
+/** The page whose `version:` is the version of the recovery-words wording (#1928). */
+export const RECOVERY_WORDS_DOCUMENT = 'recovery-words';
+/**
+ * The scope of an admin's confirmation that they saved the organization's
+ * shared-folders recovery words (#2124, epic #1775 decision 4). Like
+ * `recovery-words` it never holds a session: it is asked where the words are
+ * shown (Admin → Backup), and until the admin who was shown them confirms,
+ * holders of `admin-system` see a banner. Bound to a subject: the
+ * organization's set of words (`SharedFolderManager.recoveryWordsInfo().wordsId`),
+ * so a new set asks again.
+ */
+export const SHARED_FOLDERS_WORDS_CONSENT_SCOPE = 'shared-folders-recovery-words';
+/** The page whose `version:` is the version of the shared-folders recovery-words wording (#2124). */
+export const SHARED_FOLDERS_WORDS_DOCUMENT = 'shared-folders-recovery-words';
+/** Core's scopes bound to a subject, each with its one document (#1928, #2124). */
+export const SUBJECT_CONSENT_DOCUMENTS = {
+    [RECOVERY_WORDS_CONSENT_SCOPE]: RECOVERY_WORDS_DOCUMENT,
+    [SHARED_FOLDERS_WORDS_CONSENT_SCOPE]: SHARED_FOLDERS_WORDS_DOCUMENT
+};
+/** Scopes whose acceptance is about one thing (a subject), not the account as a whole (#1928). */
+export const SUBJECT_CONSENT_SCOPES = Object.keys(SUBJECT_CONSENT_DOCUMENTS);
+/** Scopes core reserves: an add-on can never register one as its slug. */
+export const RESERVED_CONSENT_SCOPES = [CORE_CONSENT_SCOPE, ...SUBJECT_CONSENT_SCOPES];
 /**
  * Thrown when a per-person add-on is turned on before its documents are
  * accepted (#1603). `documents` names what is still to accept.

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

@@ -166,6 +166,12 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_EXTEND: "share-extend";
     /** Share link revoked; pairs with token-revoke */
     readonly SHARE_REVOKE: "share-revoke";
+    /** 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 */
+    readonly SHARED_FOLDER_KEY_CREATE: "shared-folder-key-create";
+    /** The organization's 12 recovery words for shared folders were made and saved (#2124): the admin who was shown them, and which set (an id, never the words). Recorded before the words are saved, which cannot proceed without it */
+    readonly SHARED_FOLDER_WORDS_CREATE: "shared-folder-words-create";
+    /** An administrator discarded the organization's shared-folders recovery words before the admin shown them confirmed saving them (#2124): who, which set (an id) and who it was shown to. Recorded before the words are removed, which cannot proceed without it */
+    readonly SHARED_FOLDER_WORDS_DISCARD: "shared-folder-words-discard";
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     readonly SIGNINAPPROVAL_ABANDON: "signinapproval-abandon";
     /** Sign-in approval: the user pressed Approve (#1532) */

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

@@ -173,6 +173,12 @@ export const AUDIT_EVENT = {
     SHARE_EXTEND: 'share-extend',
     /** Share link revoked; pairs with token-revoke */
     SHARE_REVOKE: 'share-revoke',
+    /** 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 */
+    SHARED_FOLDER_KEY_CREATE: 'shared-folder-key-create',
+    /** The organization's 12 recovery words for shared folders were made and saved (#2124): the admin who was shown them, and which set (an id, never the words). Recorded before the words are saved, which cannot proceed without it */
+    SHARED_FOLDER_WORDS_CREATE: 'shared-folder-words-create',
+    /** An administrator discarded the organization's shared-folders recovery words before the admin shown them confirmed saving them (#2124): who, which set (an id) and who it was shown to. Recorded before the words are removed, which cannot proceed without it */
+    SHARED_FOLDER_WORDS_DISCARD: 'shared-folder-words-discard',
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     SIGNINAPPROVAL_ABANDON: 'signinapproval-abandon',
     /** Sign-in approval: the user pressed Approve (#1532) */

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

@@ -78,9 +78,9 @@ export declare function sealKekCopy(recipient: LinkPublicKey, kek: Buffer): Prom
  * their private key from `envelope`, which opens `copy`. Throws when any step
  * fails; the private key never leaves this function.
  */
-export declare function openKekCopy(envelope: UserKeyEnvelope, ownKek: Buffer, copy: Lockbox): Promise<Buffer>;
+export declare function openKekCopy(envelope: Pick<UserKeyEnvelope, 'personKey'>, ownKek: Buffer, copy: Lockbox): Promise<Buffer>;
 export declare function unwrapKekWithPassword(envelope: UserKeyEnvelope, password: string): Promise<Buffer>;
-export declare function unwrapKekWithMnemonic(envelope: UserKeyEnvelope, mnemonic: string): Buffer;
+export declare function unwrapKekWithMnemonic(envelope: Pick<UserKeyEnvelope, 'recoveryWrap'>, mnemonic: string): Buffer;
 /**
  * A fresh set of 12 recovery words for a KEK that has not been committed yet
  * (#1414): the store door's words screen, where a failed confirmation discards
@@ -91,6 +91,14 @@ export declare function newRecoveryWords(kek: Buffer): {
     mnemonic: string;
     recoveryWrap: WrappedBlob;
 };
+/**
+ * Which set of recovery words an envelope holds (#1928), as a short id: a
+ * digest of the recovery wrap, which a new set of words replaces and nothing
+ * else changes (a password change or a new person key keep it). Reveals
+ * nothing about the words or the key; it is what a recorded "I saved my
+ * recovery words" is bound to, so a new set asks again.
+ */
+export declare function recoveryWordsId(envelope: Pick<UserKeyEnvelope, 'recoveryWrap'>): string;
 /** True when two phrases are the same 12 words, compared as the recovery wrap reads them. */
 export declare function sameMnemonic(entered: string, expected: string): boolean;
 export declare function rewrapPassword(envelope: UserKeyEnvelope, oldPassword: string, newPassword: string, opts?: {

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

@@ -52,6 +52,8 @@ export declare function unlockPrivateStoresWithMnemonic(args: {
 }): Promise<boolean>;
 /** Whether `username` has keys at all, i.e. a store that can be encrypted. */
 export declare function hasUserKeys(pagesDirectory: string, username: string): Promise<boolean>;
+/** Which set of recovery words `username` has (#1928, `recoveryWordsId`), or null when they have no keys. */
+export declare function recoveryWordsIdOf(pagesDirectory: string, username: string): Promise<string | null>;
 /**
  * The public half of `username`'s key pair (#1762 slice 5), or null when they
  * have no keys or no pair yet. Public: anyone may seal to it.

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

@@ -11,7 +11,7 @@
  * recipient's browser opens each lockbox with the private key from the link.
  *
  * The algorithm is WebCrypto's own, so the server (Node's `crypto.webcrypto`)
- * and the browser (`window.crypto.subtle`, public/js/share-viewer.js) run the
+ * and the browser (`window.crypto.subtle`, public/share/_assets/share-viewer.js) run the
  * same steps: ECDH on P-256 between a fresh ephemeral key and the link's key,
  * HKDF-SHA-256 over the shared secret, AES-256-GCM over the content.
  */

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

@@ -0,0 +1,17 @@
+/** The environment variable holding the shared-folders key. Never a config key: config is readable from the admin screens. */
+export declare const SHARED_FOLDERS_KEY_ENV = "NGDPBASE_SHARED_FOLDERS_KEY";
+/** The shared-folders key as set now, trimmed; '' when there is none. Never logged. */
+export declare function currentSharedFoldersKey(): string;
+/**
+ * A short fingerprint of the shared-folders key: the first 16 hex digits of an
+ * HMAC of a fixed label under the key, as for the backup key. Shown on Admin →
+ * Backup and recorded with the wrapped folder keys, so a different key says so
+ * plainly; it never reveals the key.
+ */
+export declare function sharedFoldersKeyFingerprint(key: string): string;
+/**
+ * The 32-byte key the folder keys are wrapped under, derived from the `.env`
+ * value (HKDF-SHA256, one HMAC round: cheap, never a stall). Derived, not
+ * decoded, so a value an operator set themselves in any form still works.
+ */
+export declare function sharedFoldersWrapKey(key: string): Buffer;

package/lib/src/utils/sharedFoldersKey.js

@@ -0,0 +1,33 @@
+/**
+ * The shared-folders key (#2124, epic #1775 decision 1): the organization's
+ * server-held key, `NGDPBASE_SHARED_FOLDERS_KEY`, in the instance `.env`
+ * beside the backup, database and credentials keys. Generated on first start
+ * (`bootstrap-env.ts`), read at startup by SharedFolderManager, which wraps
+ * every shared folder's own key under it. One declaration here, with no
+ * dependencies, so the boot can name it without loading the manager, and
+ * BackupManager can fingerprint it for the "saved off the server" check.
+ */
+import { createHmac, hkdfSync } from 'node:crypto';
+/** The environment variable holding the shared-folders key. Never a config key: config is readable from the admin screens. */
+export const SHARED_FOLDERS_KEY_ENV = 'NGDPBASE_SHARED_FOLDERS_KEY';
+/** The shared-folders key as set now, trimmed; '' when there is none. Never logged. */
+export function currentSharedFoldersKey() {
+    return (process.env[SHARED_FOLDERS_KEY_ENV] ?? '').trim();
+}
+/**
+ * A short fingerprint of the shared-folders key: the first 16 hex digits of an
+ * HMAC of a fixed label under the key, as for the backup key. Shown on Admin →
+ * Backup and recorded with the wrapped folder keys, so a different key says so
+ * plainly; it never reveals the key.
+ */
+export function sharedFoldersKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase shared folders key fingerprint v1').digest('hex').slice(0, 16);
+}
+/**
+ * The 32-byte key the folder keys are wrapped under, derived from the `.env`
+ * value (HKDF-SHA256, one HMAC round: cheap, never a stall). Derived, not
+ * decoded, so a value an operator set themselves in any form still works.
+ */
+export function sharedFoldersWrapKey(key) {
+    return Buffer.from(hkdfSync('sha256', key, Buffer.alloc(0), 'ngdpbase shared folders wrap key v1', 32));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.38.0",
+  "version": "5.39.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -44,6 +44,7 @@
     "dotenv": "^18.0.9",
     "express": "^5.3.0",
     "express-session": "^1.19.0",
+    "fast-xml-parser": "^5.11.2",
     "fs-extra": "^11.4.1",
     "ipaddr.js": "^2.5.0",
     "jose": "^6.2.13",