@jwilleke/ngdpbase-types 5.24.0 → 5.26.0

package/README.md

@@ -11,7 +11,7 @@ import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-type
 import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
 ```
 
-- The main entry is types only. Importing it at run time fails, on purpose.
-- `/testing` is for tests. `buildAddonHost(slug, defaults)` is the real host. `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
+- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
+- `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

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

@@ -14,8 +14,8 @@
  * `@jwilleke/ngdpbase-types/testing`. A test holds this file to `export type`
  * only, so the published entry carries no JavaScript.
  */
-export type { AddonModule } from '../../src/managers/AddonsManager.js';
-export type { AddonHost } from '../../src/utils/addonHost.js';
+export type { AddonModule, AddonManifest, AddonListing } from '../../src/managers/AddonsManager.js';
+export type { AddonHost, PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export type { WikiEngine } from '../../src/types/WikiEngine.js';
 export type { ApiContext } from '../../src/context/ApiContext.js';
 export type { ActorContext } from '../../src/context/ActorContext.js';
@@ -30,6 +30,10 @@ export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
 export type { default as ExportManager } from '../../src/managers/ExportManager.js';
 export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';
+export type { default as PageManager } from '../../src/managers/PageManager.js';
+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 PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';

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

@@ -4,7 +4,7 @@
 import ExportManager from '../../src/managers/ExportManager.js';
 import { type AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
 import { type SqliteHandle } from '../../src/providers/SqliteDatabaseProvider.js';
-import { type AddonHost } from '../../src/utils/addonHost.js';
+import { buildAddonHost as buildHost, type AddonHost, type PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export { formatters } from '../../src/managers/PluginManager.js';
 /**
  * Core's `buildAddonHost`, with the audit registry bound to this add-on's
@@ -15,8 +15,13 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - The add-on's own `config/default-config.json`
+ * @param setEnabledForPerson - What `host.setEnabledForPerson` does in the
+ *   test (#1963); a site binds core's setter. Without one it refuses.
+ * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
+ *   names the system principal for `host.systemContext`; without one it is
+ *   core's fallback principal
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof buildHost>[3]): AddonHost;
 /** The add-on whose declaration a test database is checked against: its slug and its own `config/default-config.json`. */
 export interface AddonTestDatabaseDeclarer {
     slug: string;

package/lib/packages/ngdpbase-types/testing.js

@@ -14,10 +14,15 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - The add-on's own `config/default-config.json`
+ * @param setEnabledForPerson - What `host.setEnabledForPerson` does in the
+ *   test (#1963); a site binds core's setter. Without one it refuses.
+ * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
+ *   names the system principal for `host.systemContext`; without one it is
+ *   core's fallback principal
  */
-export function buildAddonHost(slug, addonDefaults) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson, engine) {
     bindAuditEvents((key, fallback) => addonDefaults[key] ?? fallback);
-    return buildHost(slug, addonDefaults);
+    return buildHost(slug, addonDefaults, setEnabledForPerson, engine);
 }
 /**
  * An add-on's database as `DatabaseManager.openAddonDatabase` returns it, in

package/lib/src/http/egressPolicy.js

@@ -0,0 +1,61 @@
+/**
+ * Configuration to policy (#1133).
+ *
+ * The operator sets two CIDR lists; this turns them into the `EgressPolicy`
+ * the guard enforces, and reconciles them at BOOT so a contradiction is a
+ * startup message rather than one dropped image months later — which would
+ * surface as a `fetch` warning indistinguishable from the remote host being
+ * down.
+ *
+ * Contradictions resolve by FIREWALL CONVENTION and none of them stops the
+ * boot (#1144, D8). #1133 chose longest-prefix match — the routing rule,
+ * because the values are routes — so a general overlap is not a conflict at
+ * all. The cases longest prefix cannot decide are settled here: an allow entry
+ * reaching the mechanism is unsatisfiable and dropped, and a range in both
+ * lists is a prefix-length tie the DENY wins.
+ *
+ * `ngdpbase.security.profile` used to decide whether a contradiction stopped
+ * the boot. That was the profile looking for a job: `iptables` rejects a bad
+ * rule and keeps the chain, and the Kubernetes API server rejects an invalid
+ * NetworkPolicy while the others keep applying. Neither takes the workload
+ * down. The one case with no safe silent resolution — a malformed range, where
+ * dropping a DENY fails open — is reported separately for #1152.
+ */
+import { reconcilePolicy } from './ssrf.js';
+export const DENIED_RANGES_KEY = 'ngdpbase.security.egress.denied-ranges';
+export const ALLOWED_RANGES_KEY = 'ngdpbase.security.egress.allowed-ranges';
+/** Only strings can be CIDRs; anything else in the list is discarded, not coerced. */
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * Read the configured ranges, reconcile them, and report what could not be
+ * resolved.
+ *
+ * A contradiction never widens access. Where the two lists disagree the
+ * stricter reading wins, which is the only direction a security control should
+ * fail when nobody can be asked.
+ */
+export function resolveEgressPolicy(read) {
+    const deniedRanges = stringList(read(DENIED_RANGES_KEY, []));
+    const allowedRanges = stringList(read(ALLOWED_RANGES_KEY, []));
+    const { conflicts, malformed, duplicates } = reconcilePolicy(deniedRanges, allowedRanges);
+    const unusable = new Set(malformed);
+    // An allow entry is dropped when it cannot be parsed, when it reaches the
+    // mechanism, or when the same range is also denied. The last is D8's tie
+    // break: equal prefix lengths give longest-prefix nothing to work with, so
+    // the deny wins.
+    const safeAllowed = allowedRanges.filter((range) => !unusable.has(range)
+        && !duplicates.includes(range)
+        && !conflicts.some((c) => c.startsWith('allowed-ranges:') && c.includes(`'${range}'`)));
+    // A denied range is dropped ONLY when it cannot be parsed. Previously a
+    // range appearing in both lists was removed from here too, so the operator's
+    // stricter statement was discarded along with the looser one and the range
+    // fell back to the built-in defaults.
+    const safeDenied = deniedRanges.filter((range) => !unusable.has(range));
+    return {
+        policy: { deniedRanges: safeDenied, allowedRanges: safeAllowed },
+        conflicts,
+        malformed
+    };
+}

package/lib/src/http/guardedElasticsearch.d.ts

@@ -0,0 +1,27 @@
+import { Client, type ClientOptions } from '@elastic/elasticsearch';
+import { type Resolver } from './guardedLookup.js';
+import { type ConfigReader } from './egressPolicy.js';
+import { type EgressPolicy } from './ssrf.js';
+export interface GuardedElasticsearchOptions {
+    /** Per-request timeout in ms; the SDK's default when omitted. */
+    requestTimeout?: number;
+    /**
+     * The resolution step, for tests only — the same single seam `guardedLookup`
+     * exposes. Production leaves it unset and `node:dns` answers.
+     */
+    resolver?: Resolver;
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export declare function guardedClientOptions(node: string, policy: EgressPolicy, options?: GuardedElasticsearchOptions): ClientOptions;
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export declare function createGuardedElasticsearchClient(node: string, read: ConfigReader, options?: GuardedElasticsearchOptions): Client;
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export declare function refusedNodeMessage(who: string, node: string, reason: string): string;

package/lib/src/http/guardedElasticsearch.js

@@ -0,0 +1,99 @@
+/**
+ * The Elasticsearch client, built inside the boundary (#1188).
+ *
+ * `@elastic/elasticsearch` opens sockets the same way `fetch` does, and until
+ * #1188 it did so from two places outside `src/http/` — the search provider
+ * and the elasticsearch addon — with `new Client({ node })` and no policy at
+ * all. The boundary check (#1139) could not see it because the SDK was not in
+ * its list of client modules, so the guard read green while the process
+ * connected to whatever `es-url` said, loopback and RFC1918 included.
+ *
+ * This is the only place the SDK is constructed. It hands the client Node's
+ * `http` connection class with agents whose `lookup` is the guarded one, so
+ * every socket the client opens — the first request, a retry, a sniffed node —
+ * is judged against the instance's egress policy at connect time, exactly as
+ * `guardedFetch` does. There is no ungated constructor to reach for: the
+ * scanner now names the SDK, so an `import { Client }` outside this directory
+ * fails `lint:http`.
+ *
+ * What this means for an operator: an Elasticsearch node on `localhost` is
+ * refused — loopback is mechanism, not policy (#1186), and no allow entry
+ * opens it. A node on the LAN needs its prefix in
+ * `ngdpbase.security.egress.allowed-ranges`, the same as sist2. Both call
+ * sites say so at boot when the configured address would be refused.
+ */
+import { Agent as HttpAgent } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { isIP } from 'node:net';
+import { Client, HttpConnection } from '@elastic/elasticsearch';
+import { ESSRF_BLOCKED, guardedLookup } from './guardedLookup.js';
+import { resolveEgressPolicy } from './egressPolicy.js';
+import { isAddressAllowed, REFUSAL } from './ssrf.js';
+/**
+ * The connect step, guarding the case the lookup never sees.
+ *
+ * Node calls an agent's `lookup` only for a NAME. A URL whose host is an IP
+ * literal — `http://192.168.0.10:9200`, `http://127.0.0.1:9200` — goes
+ * straight to the socket, so a guard that lives only in `lookup` waves every
+ * literal address through. Found by pointing the first version of this at
+ * jimstest's LAN node under an empty policy and watching `ping` return true.
+ * `guardedFetch` covers the same hole with `validateUrl` before each hop;
+ * here the judgement sits in `createConnection`, which every socket passes
+ * through, literal or resolved.
+ */
+function guardedCreateConnection(policy, connect) {
+    return function guarded(options, callback) {
+        const host = String(options.host ?? options.hostname ?? 'localhost');
+        if (isIP(host) && !isAddressAllowed(host, policy)) {
+            const err = Object.assign(new Error(`${REFUSAL}: ${host}`), { code: ESSRF_BLOCKED });
+            if (callback) {
+                process.nextTick(callback, err);
+                return undefined;
+            }
+            throw err;
+        }
+        // Node's own connect for this agent — `net.createConnection` for http,
+        // the TLS one for https. The agent has merged its options in, so `lookup`
+        // (the guarded one) rides along for a host that is a name.
+        return connect.call(this, options, callback);
+    };
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export function guardedClientOptions(node, policy, options = {}) {
+    // keepAlive stays on, as the SDK's own default agent has it: a kept socket
+    // was judged when it was opened, and both guards run again for every new one.
+    const lookup = guardedLookup(policy, options.resolver);
+    const agents = { http: new HttpAgent({ lookup, keepAlive: true }), https: new HttpsAgent({ lookup, keepAlive: true }) };
+    // `createConnection` is a method of the agent, not an option it accepts:
+    // Node reads `this.createConnection` when it opens a socket. Replaced on the
+    // instance, wrapping the prototype's own so TLS setup stays Node's.
+    const method = (agent) => Object.getPrototypeOf(agent).createConnection;
+    agents.http.createConnection =
+        guardedCreateConnection(policy, method(agents.http));
+    agents.https.createConnection =
+        guardedCreateConnection(policy, method(agents.https));
+    return {
+        node,
+        ...(options.requestTimeout !== undefined ? { requestTimeout: options.requestTimeout } : {}),
+        Connection: HttpConnection,
+        agent: (connection) => (connection.url.protocol === 'https:' ? agents.https : agents.http)
+    };
+}
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export function createGuardedElasticsearchClient(node, read, options = {}) {
+    return new Client(guardedClientOptions(node, resolveEgressPolicy(read).policy, options));
+}
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export function refusedNodeMessage(who, node, reason) {
+    return (`[${who}] Elasticsearch node ${node} is refused by the egress policy (${reason}). ` +
+        'Loopback and link-local can never be opened; a LAN address needs its prefix in ' +
+        'ngdpbase.security.egress.allowed-ranges. Every request to it will fail. (#1188)');
+}

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

@@ -10,13 +10,15 @@
  *
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/158}
  */
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import type { BackupFolder } from './BaseManager.js';
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { User } from '../types/User.js';
 import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
 import { type AddonHost } from '../utils/addonHost.js';
+import { ConsentRequiredError } from '../types/Consent.js';
 /**
  * Type passed to `AddonModule.profileSection()` (#534). Matches what
  * `UserManager.getUser()` returns at runtime — `User` minus the password
@@ -76,6 +78,14 @@ export interface AddonModule {
      * frozen. An add-on that takes two arguments keeps working until it moves.
      */
     register(engine: WikiEngine, config: Record<string, unknown>, host?: AddonHost): Promise<void> | void;
+    /**
+     * Folders it keeps data in besides its `dataPath` (#1985), given its
+     * configuration. Its `dataPath` is backed up and restored without being
+     * declared; an add-on declares only further folders, and writes no backup
+     * code. BackupManager archives each one, stages it in a site restore, and
+     * puts it in place before `register()` runs at the next start.
+     */
+    backupFolders?(config: Record<string, unknown>): BackupFolder[];
     /**
      * Optional health check returning add-on status details.
      */
@@ -208,7 +218,49 @@ export interface AddonManifest {
      * docs/guides/addons-developer-guide.md "Declare a Private Store".
      */
     stores?: unknown;
+    /**
+     * #1963: each person turns this add-on on or off for themselves. Their
+     * switch is the preference `<slug>.enabled` (`personSwitchKey`), read only
+     * by `AddonsManager.enabledAddonsFor` and written only through
+     * `host.setEnabledForPerson`. Absent or anything but `true`: not per-person.
+     */
+    perPerson?: boolean;
+    /**
+     * #1965: the add-on's About page, a page it ships in `pages/`, by uuid or
+     * slug. `[{ConfigAccessor type='addons'}]` links to it ("More about it").
+     * The site overrides it with `ngdpbase.addons.<slug>.about-page`.
+     */
+    aboutPage?: string;
+    /**
+     * #1965: the heading the add-on is listed under, shared by related add-ons
+     * (e.g. "Accounting" for accounting, accounting-donations and accounting-dues).
+     */
+    family?: string;
+    /** #1965: `false` keeps plumbing (e.g. elasticsearch) out of the add-on listings. */
+    listed?: boolean;
+}
+/**
+ * One add-on as the listings show it (#1965), from `AddonsManager.listedAddons()`.
+ * `version`, `loaded` and `error` are for administrators; the plugin that
+ * renders a listing decides who sees them.
+ */
+export interface AddonListing {
+    slug: string;
+    description: string;
+    /** The heading it is grouped under, or null */
+    family: string | null;
+    /** The About page (uuid or slug), the site's override first; null when none */
+    aboutPage: string | null;
+    perPerson: boolean;
+    version: string;
+    loaded: boolean;
+    error: string | null;
 }
+/**
+ * The preference that holds a person's switch for a per-person add-on (#1963):
+ * `<slug>.enabled`. The one place the key is spelled.
+ */
+export declare function personSwitchKey(slug: string): string;
 /**
  * Details returned by add-on's status() method
  */
@@ -262,6 +314,7 @@ export interface AddonStatus {
  * AddonsManager - Manages optional add-on modules
  */
 declare class AddonsManager extends BaseManager {
+    #private;
     /** Map of discovered add-ons by name */
     private addons;
     /** Configured paths to addons directories (one or more) */
@@ -282,6 +335,8 @@ declare class AddonsManager extends BaseManager {
     private domainAddonName;
     /** #1883: the enabled add-ons that did not load this start, with why — each reported once. */
     private readonly loadFailures;
+    /** #1973: every enabled add-on has had its turn to load this boot (see {@link addonsLoaded}). */
+    private loadPassDone;
     constructor(engine: WikiEngine);
     /**
      * Initialize the AddonsManager
@@ -405,6 +460,34 @@ declare class AddonsManager extends BaseManager {
         ok: false;
         blockedBy: string[];
     };
+    /**
+     * The installed version of an add-on (#1973): the `version` in its
+     * package.json, or its module's `version` when the package.json has none.
+     * Undefined for an add-on that was not discovered.
+     *
+     * @param slug - The add-on's slug
+     */
+    getAddonVersion(slug: string): string | undefined;
+    /**
+     * Whether this boot's load pass is over (#1973): every enabled add-on has
+     * had its `register()` called, loaded or not. Until then, what an add-on has
+     * not registered yet says nothing about whether it still provides it.
+     */
+    addonsLoaded(): boolean;
+    /**
+     * An add-on's folders (#1985): its `dataPath` — `ngdpbase.addons.<slug>.dataPath`,
+     * or `<FAST_STORAGE>/<slug>` when that is not set, as the bundled add-ons
+     * read it — under the part name of its slug, then any further folders its
+     * module declares. A `dataPath` that is the instance data folder, or holds
+     * it, is never one: a restore would swap the whole site's data.
+     */
+    private addonFolders;
+    /** Each loaded add-on's `dataPath` and declared folders (#1985), in load order: what BackupManager backs up for it. */
+    addonBackupFolders(): Array<{
+        slug: string;
+        dataPath: string | null;
+        folders: BackupFolder[];
+    }>;
     /**
      * Get add-on specific configuration
      */
@@ -612,8 +695,42 @@ declare class AddonsManager extends BaseManager {
      *
      * Errors are caught per-addon and logged so one bad addon cannot block
      * other addons' saves or the core-preferences save.
+     *
+     * #1603: an add-on whose switch was refused because its documents are not
+     * accepted yet (`ConsentRequiredError`) is returned, so the route can tell
+     * the person what to accept instead of the save failing silently.
+     */
+    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<{
+        consentRequired: ConsentRequiredError[];
+    }>;
+    /**
+     * The add-ons the site's listings show (#1965): enabled, and not
+     * `listed: false` in their manifest, in load order. Cheap: it calls no
+     * add-on's status(), so a page can render it.
+     */
+    listedAddons(): AddonListing[];
+    /**
+     * Whether `slug` is an add-on whose manifest says `perPerson: true` (#1963),
+     * loaded or still loading. ConsentManager asks it when an add-on registers
+     * documents: they guard the per-person switch, so only such an add-on has any.
+     */
+    isPerPerson(slug: string): boolean;
+    /** #1963: the loaded add-ons whose manifest says `perPerson: true`, in load order. */
+    private perPersonAddons;
+    /**
+     * The per-person add-ons this subject has turned on (#1963): each loaded
+     * add-on whose manifest says `perPerson: true` and whose switch, the
+     * person's preference `<slug>.enabled`, is `true`.
+     *
+     * It reads exactly those keys and no other preference, so no access check
+     * or listing built on it can come to depend on an arbitrary setting. An
+     * anonymous subject, an unknown or inactive account, and the system
+     * principal (which has no account) have none.
+     *
+     * @param ctx - Whose add-ons: the request's subject, or a job's context
+     * @returns The slugs, in load order
      */
-    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<void>;
+    enabledAddonsFor(ctx: ActorContext): Promise<string[]>;
     /**
      * Get count of loaded add-ons
      */

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

@@ -1,6 +1,5 @@
-import BaseManager, { BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import BaseManager, { BackupData, type BackupArchiveTarget, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats, type SiteRestoreStaging, type StagedRestoreAtStart } from './BaseManager.js';
 import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from '../providers/attachmentFilesBackup.js';
-import type { PartOutcome } from '../utils/siteRestore.js';
 import { type ActorContext } from '../context/ActorContext.js';
 /**
  * Marks an error as "the audit record could not be written", not "the action
@@ -36,11 +35,11 @@ interface BaseAttachmentProvider {
     backup(): Promise<unknown>;
     restore(backupData: unknown): Promise<void>;
     /** #1876: the files themselves beside the backup document, and their staged restore. */
-    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
-    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+    backupFiles?(archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, siteRestore: SiteRestoreStaging): Promise<{
         skippedVaults: string[];
     }>;
-    takeRestoreAtStart?(): PartOutcome | null;
+    takeRestoreAtStart?(): StagedRestoreAtStart | null;
     shutdown(): Promise<void>;
     getProviderInfo(): {
         features: string[];