@jwilleke/ngdpbase-types 5.37.0 → 5.39.0

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/security/permissions.generated.d.ts

@@ -22,6 +22,8 @@ export type CorePermission =
  | 'comment-create'
 /** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
  | 'config-manage'
+/** Open the Executive Hub (/executive): the organization's summary cards and the requests waiting for the board (#2093). Held by the executive role; deciding a request still needs that request's own permission */
+ | 'executive-read'
 /** Create, edit, delete and link identity records, of users and contacts alike, and organizations, and an identity's affiliations, through IdentityManager and OrganizationManager (#1930). Reading them is identity-read. Was contact-manage until #2038; a policy naming that is still read as this for one release. Admins by default; an add-on grants it to its own roles in its own policy */
  | 'identity-manage'
 /** List, search and view identity records, of users and contacts alike, and organizations, and their affiliations, through IdentityManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Was contact-read until #2038; a policy naming that is still read as this for one release. Admins and demo admins by default; an add-on grants it to its own roles in its own policy */

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

@@ -58,6 +58,8 @@ export declare const AUDIT_EVENT: {
     readonly EMAILCHANGE_CONFIRM: "emailchange-confirm";
     /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
     readonly EMAILCHANGE_REQUEST: "emailchange-request";
+    /** Executive Hub read; not recorded, read volume */
+    readonly EXECUTIVE_READ: "executive-read";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
@@ -164,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

@@ -65,6 +65,8 @@ export const AUDIT_EVENT = {
     EMAILCHANGE_CONFIRM: 'emailchange-confirm',
     /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
     EMAILCHANGE_REQUEST: 'emailchange-request',
+    /** Executive Hub read; not recorded, read volume */
+    EXECUTIVE_READ: 'executive-read',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
@@ -171,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?: {