@jwilleke/ngdpbase-types 5.41.1 → 5.43.0

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

@@ -19,6 +19,12 @@ export interface AgentTokenGrant {
     id: string;
     name: string;
     scopes: string[];
+    /**
+     * The assurance level stored with the token when it was made (#2261): the
+     * level of the minting session at that moment, never higher. Absent on a
+     * token made before it was stored, which then has no `subject:aal`.
+     */
+    aal?: 1 | 2 | 3;
 }
 /**
  * A person acting for another under a proxy grant (#1762 slice 2), as a
@@ -112,6 +118,12 @@ export interface PermissionSubject {
      * account's cap, since it is the actor who signs in (#1762).
      */
     aalCap?: import('../providers/BaseAuthProvider.js').Aal;
+    /**
+     * Set by the bearer middleware on a subject authenticated by a JWT that
+     * records no sign-in level (Authentik, #2287): its `subject:aal` is missing,
+     * not AAL 1. Set from the verified result, never from a request field.
+     */
+    bearerWithoutLevel?: true;
 }
 /**
  * The subject of work with no request behind it (#631, #1212).
@@ -134,6 +146,8 @@ export interface JobSubject {
     viaProxy?: ProxyClaim;
     /** #1999: the scheduled job a run acts as (`JobContext.job`). */
     job?: string;
+    /** #2261: the level stored with the job's request (`JobContext.aal`); absent when it stored none. */
+    grantedAal?: 1 | 2 | 3;
 }
 /**
  * User creation input data
@@ -426,11 +440,11 @@ declare class UserManager extends BaseManager {
     /**
      * Create a user page for a new user.
      *
-     * The page is written AS the new user (#1462): it is their page, and the
-     * door takes a new page's author from who is acting. Written as the admin
-     * who created the account — or as whoever ran self-registration — the
-     * profile would be authored by them, and `author-lock` would leave the
-     * account's own owner unable to edit it.
+     * The page is the new user's (#1462): they are its author. Authored by the
+     * admin who created the account — or by whoever ran self-registration —
+     * `author-lock` would leave the account's own owner unable to edit it.
+     * It is written by a system job through the write door (#1815), with the
+     * new user named as the one it is made for.
      *
      * @param {User} user - User object
      * @param ctx - Who created the account, for the log line only

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

@@ -48,8 +48,10 @@ export declare const DEFAULT_SHARE_MAX_DAYS = 15;
  * - `public`: a `storageLocation` without a vault; its pages can never be
  *   private.
  * - `vault`: a `storageLocation.privatestore`; its pages may be private.
+ * - `shared-folder`: `storageLocation.sharedfolder: true` (#2255); its pages
+ *   live in shared folders (the `shared` category).
  */
-export type CategoryStored = 'none' | 'public' | 'vault';
+export type CategoryStored = 'none' | 'public' | 'vault' | 'shared-folder';
 /**
  * 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

package/lib/src/providers/AgentTokenAuthProvider.js

@@ -39,7 +39,7 @@ export class AgentTokenAuthProvider {
             return null;
         return {
             username: record.owner,
-            viaToken: { id: record.id, name: record.name, scopes: record.scopes }
+            viaToken: { id: record.id, name: record.name, scopes: record.scopes, ...(record.aal ? { aal: record.aal } : {}) }
         };
     }
 }

package/lib/src/providers/BaseAttachmentProvider.d.ts

@@ -160,6 +160,10 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
     filesInStoreForPage(_location: StoreFileLocation, _pageName: string): Promise<StoreFileEntry[]>;
     /** Delete a file from a store: its bytes and its index entry. Null when the store does not list it. */
     deleteFileInStore(_location: StoreFileLocation, _id: string): Promise<StoreFileEntry | null>;
+    /** The ids a takeout import gave a store's files that could not keep their own, as takeout id → id here (#2188). */
+    readStoreRenumbered(_location: StoreFileLocation): Promise<Map<string, string>>;
+    /** Adds takeout id → id pairs to {@link readStoreRenumbered}'s (#2188). */
+    noteStoreRenumbered(_location: StoreFileLocation, _pairs: ReadonlyMap<string, string>): Promise<void>;
     /**
      * Refresh internal cache/index
      * Re-scans storage and rebuilds indexes

package/lib/src/providers/BaseAuditProvider.d.ts

@@ -0,0 +1,492 @@
+import { AuditEvent } from '../types/index.js';
+import type { ProviderInfo } from '../types/Provider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import BaseProvider, { type ProviderDurability } from './BaseProvider.js';
+import { type ActorContext } from '../context/ActorContext.js';
+/**
+ * Audit search filters
+ */
+export interface AuditFilters {
+    /** Filter by username — the account acted on */
+    user?: string;
+    /** Filter by the person who actually acted, under a proxy grant (#1762) */
+    actor?: string;
+    /** Filter by event type */
+    eventType?: string;
+    /** Filter by result (allow, deny, error) */
+    result?: string;
+    /** Filter by severity level */
+    severity?: string;
+    /** Start date filter */
+    startDate?: Date;
+    /** End date filter */
+    endDate?: Date;
+    /** Filter by resource */
+    resource?: string;
+    /** Filter by action */
+    action?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Results offset for pagination */
+    offset?: number;
+    /** Sort field */
+    sortBy?: string;
+    /** Sort order (asc/desc) */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Audit search results
+ */
+export interface AuditSearchResults {
+    /** Array of audit events */
+    results: AuditEvent[];
+    /** Total matching events */
+    total: number;
+    /** Result limit */
+    limit: number;
+    /** Result offset */
+    offset: number;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+/**
+ * Audit statistics
+ */
+export interface AuditStats {
+    /** Total number of events */
+    totalEvents: number;
+    /** Events by type */
+    eventsByType?: Record<string, number>;
+    /** Events by result */
+    eventsByResult?: Record<string, number>;
+    /** Events by severity */
+    eventsBySeverity?: Record<string, number>;
+    /** Events by user */
+    eventsByUser?: Record<string, number>;
+    /** Recent activity entries */
+    recentActivity?: AuditEvent[];
+    /** Number of security incidents (high/critical severity) */
+    securityIncidents?: number;
+    /** Additional statistics */
+    [key: string]: unknown;
+}
+/**
+ * Paging for the entries about one person (#1537): the newest first.
+ */
+export interface PersonEntriesOptions {
+    limit?: number;
+    offset?: number;
+    /**
+     * The user's identity `@id` (#2041). From that release on a row names the
+     * owner of its resource by `@id` in `metadata.owner`; rows written before
+     * name the owner's username. A row is about the user under either.
+     */
+    ownerId?: string;
+}
+/** Where the chain head is published (#1138), shared by every storing provider. */
+export declare const WITNESS_DESTINATION_KEY = "ngdpbase.audit.chain-witness.destination";
+export declare const WITNESS_INTERVAL_KEY = "ngdpbase.audit.chain-witness.interval-minutes";
+/** #1122, #1537: how often retention runs after boot. Hourly is far finer than a day-scale window. */
+export declare const AUDIT_RETENTION_INTERVAL_MS: number;
+/**
+ * The shape every storing provider writes (#1119, #1537): one shape, so a
+ * record reads, exports and verifies the same whichever provider wrote it.
+ */
+export interface StoredAuditRecord {
+    id: string;
+    timestamp: string;
+    level?: string;
+    eventType: string;
+    user?: string;
+    /** Who actually did it when that is not `user` — under a proxy grant (#1762). */
+    actor?: string;
+    userId?: string;
+    sessionId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    resource?: string;
+    resourceType?: string;
+    action?: string;
+    result?: string;
+    reason?: string;
+    policyId?: string;
+    policyName?: string;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    duration?: number;
+    severity?: string;
+}
+/**
+ * Normalise an incoming event into the stored record shape (#1119). Runs
+ * BEFORE the base stamps the chain: the id and timestamp assigned here are
+ * part of what gets hashed, and assigning them afterwards would mean the hash
+ * covered a record different from the one written.
+ */
+export declare function toStoredAuditRecord(auditEvent: Record<string, unknown>): StoredAuditRecord;
+/**
+ * The owner of the resource a record is about (#1537, #1825): `metadata.owner`,
+ * where token, private-store and share records carry it today. Null when the
+ * record names none.
+ */
+export declare function recordOwner(record: Record<string, unknown>): string | null;
+/**
+ * The username of the owner of the resource a record is about (#2041):
+ * `metadata.ownerUser`, written beside `metadata.owner` (the identity `@id`)
+ * so the rows about an account still list after it is deleted. Null when the
+ * record names none (every row written before #2041).
+ */
+export declare function recordOwnerUser(record: Record<string, unknown>): string | null;
+/**
+ * Whether a record is about the user `person` (#1537): the user is its `user`
+ * (the account acted on, or the user represented under a proxy grant), its
+ * `actor` (who actually did it, under a proxy grant), or the owner of the
+ * resource it names ({@link recordOwner}). The owner is the user's identity
+ * `@id` (`ownerId`) on rows written from #2041 on, with their username
+ * beside it ({@link recordOwnerUser}), and their username on rows written
+ * before, which are never rewritten; any of them matches. The username
+ * beside the `@id` is what lists the rows of an account deleted since.
+ */
+export declare function recordIsAbout(record: Record<string, unknown>, person: string, ownerId?: string): boolean;
+/**
+ * Audit backup data
+ */
+export interface AuditBackupData {
+    /** Provider name */
+    provider: string;
+    /** Initialization state */
+    initialized: boolean;
+    /** Backup timestamp */
+    timestamp: string;
+    /** Additional backup data */
+    [key: string]: unknown;
+}
+/**
+ * BaseAuditProvider - Abstract base class for audit providers
+ *
+ * Provides the interface that all audit providers must implement.
+ * Follows the provider pattern established in CacheManager, AttachmentManager, and PageManager.
+ *
+ * Audit providers implement different storage backends (file, database, cloud logging)
+ *
+ * @class BaseAuditProvider
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Whether provider has been initialized
+ *
+ * @see {@link FileAuditProvider} for file-based implementation
+ * @see {@link DatabaseAuditProvider} for database implementation
+ * @see {@link AuditManager} for usage
+ *
+ * @example
+ * class MyAuditProvider extends BaseAuditProvider {
+ *   async initialize(): Promise<void> {
+ *     const config = this.engine.getManager('ConfigurationManager');
+ *     this.auditPath = config.getProperty('audit.path');
+ *     this.initialized = true;
+ *   }
+ *
+ *   async logAuditEvent(event: AuditEvent): Promise<string> {
+ *     // Implementation
+ *     return event.id;
+ *   }
+ * }
+ */
+/** What a provider reports about itself. */
+export interface AuditReport {
+    /** Alteration of a stored record is detectable. Deletion of the tail is not — see #1138. */
+    tamperEvident: boolean;
+    /** How records reach disk, or null when the provider has not stated it. */
+    durability: ProviderDurability | null;
+    queryable: boolean;
+    /**
+     * Where and when the chain head was last published, or null when nothing
+     * publishes it (#1138).
+     *
+     * NOT a boolean. The old `offBox: boolean` was hardcoded `false`, and making
+     * it `true` would have been a claim nothing on this machine can establish —
+     * no code here can verify that a path leaves the box. So this reports the
+     * facts and the reader judges, exactly as `durability` does after #1148.
+     *
+     * Without a witness, truncation of the tail is undetectable: removing records
+     * from the end breaks no link.
+     */
+    headWitness: {
+        destination: string;
+        intervalMinutes: number;
+        lastPublishedAt: string | null;
+        lastSeq: number | null;
+    } | null;
+    /**
+     * Whether the records are encrypted where they are stored (#1537). Stated
+     * only by a provider that knows: the database provider reports whether the
+     * application database is SQLCipher-encrypted. Absent means not stated.
+     */
+    encryptedAtRest?: boolean;
+}
+declare abstract class BaseAuditProvider extends BaseProvider {
+    /** Reference to the wiki engine */
+    protected engine: WikiEngine;
+    /** Whether provider has been initialized */
+    protected initialized: boolean;
+    /**
+     * Create a new audit provider
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The WikiEngine instance
+     * @throws {Error} If engine is not provided
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the audit provider
+     *
+     * Implementations should load configuration from ConfigurationManager:
+     *   const configManager = this.engine.getManager('ConfigurationManager');
+     *   const value = configManager.getProperty('key', 'default');
+     *
+     * Do NOT read configuration files directly.
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Get provider information
+     *
+     * @returns {ProviderInfo} Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * What this provider actually guarantees (#1119).
+     *
+     * Reportable rather than inferable. A security property that has to be
+     * deduced from configuration is not one an instance can be assessed on — so
+     * an operator or an assessor asks the system instead of reading the config
+     * and hoping.
+     *
+     * `tamperEvident` follows from the chain and is therefore true for every
+     * storing provider and false for the inert one, without a subclass having to
+     * remember to say so.
+     */
+    getGuarantees(): AuditReport;
+    /** Sequence of the last record this provider stamped (#1119). */
+    protected chainSeq: number;
+    /** Hash of the last record this provider stamped (#1119). */
+    protected chainPrevHash: string;
+    /**
+     * Whether this provider chains its records (#1119).
+     *
+     * True for anything that stores events. `NullAuditProvider` overrides it: it
+     * keeps nothing, so it has nothing to chain — a legitimate state rather than
+     * a hole, provided the instance cannot then CLAIM tamper evidence, which is
+     * what `getProviderInfo().guarantees` is for.
+     */
+    protected chainEnabled(): boolean;
+    /**
+     * Resume the chain from storage, or null to start a new one (#1119).
+     *
+     * Called once, lazily, before the first record is stamped. A provider that
+     * cannot resume returns null and starts a fresh chain — honest, and visible
+     * as a `seq` restarting at 1 rather than as a silent break.
+     *
+     * @protected
+     */
+    protected loadChainHead(): Promise<{
+        seq: number;
+        hash: string;
+    } | null>;
+    /** Whether the chain head has been resumed yet. */
+    private chainResumed;
+    /**
+     * Record an audit event.
+     *
+     * __Deliberately concrete and not overridable in spirit.__ Integrity is a
+     * property of the CONTRACT, not of one implementation: stamped in a subclass
+     * it would protect that subclass only, and whether an instance were
+     * tamper-evident would depend on which storage backend was configured. "It
+     * depends on your backend" is not an answer that survives an assessment.
+     *
+     * A subclass implements {@link writeEvent} — storage — and never sees the
+     * un-stamped record, so it cannot skip the integrity step. Adding a fifth
+     * provider gets tamper evidence without having to remember it.
+     *
+     * @param auditEvent - The event to record
+     * @returns The stored event's id
+     */
+    logAuditEvent(auditEvent: AuditEvent): Promise<string>;
+    /**
+     * Begin a new chain, recording that the old one was abandoned (#1124).
+     *
+     * __Never called automatically.__ A system that silently repairs its own
+     * audit chain is worse than one that stays visibly broken, so this exists
+     * only for an explicit operator action — `npm run audit:restart-chain`.
+     *
+     * The marker is written INTO the log as an ordinary record, which is what
+     * stops it being an escape hatch: an attacker who wants a clean chain has to
+     * leave a record saying they broke it. It does not repair the past — the
+     * abandoned segment stays in the file and stays unverifiable. It only says
+     * the discontinuity is known, by whom, and why.
+     *
+     * @param reason - Why the chain is being restarted. Recorded verbatim.
+     * @param ctx - Who authorised it (#1179): the operator's context, never a bare name.
+     * @returns The id of the marker record.
+     */
+    restartChain(reason: string, ctx: ActorContext): Promise<string>;
+    /** #1138: when the chain head was last published, and what was published. */
+    private witnessPublishedAtMs;
+    private witnessLast;
+    /**
+     * Publish the chain head to the configured destination (#1138), after the
+     * records it names are stored — never before, or the next verification
+     * would report truncation.
+     *
+     * The chain cannot detect truncation of its own tail — removing records from
+     * the end breaks no link — and it cannot be fixed locally, because an
+     * attacker who owns the machine owns anything the machine wrote locally. So
+     * the head goes to wherever the operator points it, and this code takes no
+     * view on whether that is genuinely off-box (D13): it reports the
+     * destination and never claims what the destination is (D21).
+     *
+     * Failure to publish is logged and swallowed. An instance that refuses to
+     * serve because it could not write a witness would be trading a working
+     * system for a detection property, which is the wrong way round — and the
+     * absence of a fresh witness is itself visible in getGuarantees().
+     */
+    protected publishChainHead(): Promise<void>;
+    /**
+     * Where the chain head is published, or null when nothing publishes it
+     * (#1138). Facts, not a claim — see the note on AuditReport.headWitness.
+     */
+    protected headWitnessReport(): AuditReport['headWitness'];
+    /**
+     * One export format for every provider: JSON as stored, or CSV through
+     * ExportManager's writer — quoting, and no cell a spreadsheet would run as a
+     * formula.
+     */
+    protected formatExport(results: readonly AuditEvent[], format: 'json' | 'csv'): string;
+    /**
+     * The entries about one person, newest first, a page at a time (#1537):
+     * those where the person is the `user`, the `actor`, or the resource's
+     * owner ({@link recordIsAbout}). A provider that cannot answer says so,
+     * rather than returning an empty page that reads as "nothing happened".
+     */
+    searchEntriesAbout(_person: string, _options?: PersonEntriesOptions): Promise<AuditSearchResults>;
+    /**
+     * The stored record with this id, or null (#1523: a remembered browser's
+     * row names the audit record of its sign-in, and is checked against it).
+     * Null too from a provider that cannot look a record up by id.
+     */
+    findRecordById(_id: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Normalise an incoming event into the record that will be stored (#1119).
+     *
+     * Identity by default. A provider that assigns its own id, timestamp or
+     * field shape overrides this rather than doing it in {@link writeEvent},
+     * because the stamp must cover exactly what is written.
+     *
+     * @protected
+     */
+    protected prepareRecord(record: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Store an already-stamped record.
+     *
+     * @async
+     * @abstract
+     * @param record - The record to store, with seq/prevHash/hash already applied
+     * @returns {Promise<string>} Event ID
+     */
+    abstract writeEvent(record: Record<string, unknown>): Promise<string>;
+    /**
+     * Search audit logs
+     *
+     * @async
+     * @abstract
+     * @param {AuditFilters} filters - Search filters
+     * @param {Record<string, any>} options - Search options
+     * @returns {Promise<AuditSearchResults>} Search results
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract searchAuditLogs(filters?: AuditFilters, options?: Record<string, unknown>): Promise<AuditSearchResults>;
+    /**
+     * Get audit statistics
+     *
+     * @async
+     * @abstract
+     * @param {AuditFilters} filters - Optional filters
+     * @returns {Promise<AuditStats>} Audit statistics
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract getAuditStats(filters?: AuditFilters): Promise<AuditStats>;
+    /**
+     * Export audit logs
+     *
+     * @async
+     * @abstract
+     * @param {AuditFilters} filters - Export filters
+     * @param {string} format - Export format ('json', 'csv')
+     * @returns {Promise<string>} Exported data
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract exportAuditLogs(filters?: AuditFilters, format?: 'json' | 'csv'): Promise<string>;
+    /**
+     * Flush pending audit events to storage
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract flush(): Promise<void>;
+    /**
+     * Clean up old audit logs based on retention policy
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract cleanup(): Promise<void>;
+    /**
+     * Check if the audit provider is healthy
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<boolean>} True if healthy
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the audit provider
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Backup audit configuration and state (optional)
+     *
+     * Default implementation provides basic backup data.
+     * Subclasses can override to include provider-specific data.
+     *
+     * @async
+     * @returns {Promise<AuditBackupData>} Backup data
+     */
+    backup(): Promise<AuditBackupData>;
+    /**
+     * Restore audit from backup (optional)
+     *
+     * Default implementation does nothing.
+     * Subclasses can override if they support restore functionality.
+     *
+     * @async
+     * @param {AuditBackupData} _backupData - Backup data
+     * @returns {Promise<void>}
+     */
+    restore(_backupData: AuditBackupData): Promise<void>;
+}
+export default BaseAuditProvider;
+export { WikiEngine, ProviderInfo };

package/lib/src/providers/BaseAuthProvider.d.ts

@@ -46,6 +46,8 @@ export interface AuthVerifyCredentials {
     password?: string;
     /** One-time token — used by MagicLinkAuthProvider */
     token?: string;
+    /** A six-digit authenticator-app code — used by TotpAuthProvider (#421). */
+    code?: string;
     /** The account chosen for a link to a shared address (#2073) — used by MagicLinkAuthProvider. */
     account?: string;
     /** OAuth `state` from the callback — used by OidcAuthProvider */
@@ -72,6 +74,8 @@ export interface ViaToken {
     name: string;
     /** Scope ceiling this token may act within */
     scopes: string[];
+    /** The assurance level stored with the token when it was made (#2261); absent on an older token. */
+    aal?: 1 | 2 | 3;
 }
 /**
  * Returned by verify() on success.

package/lib/src/providers/BaseCredentialsProvider.d.ts

@@ -3,7 +3,7 @@
  *
  * Passwords stay on the user record and are never copied here (decided
  * 2026-10-02). This store holds passkeys, verified email / phone addresses
- * and known devices (TOTP seeds once #421 is built) — one row each, many per
+ * known devices and TOTP seeds (#421, encrypted) — one row each, many per
  * account.
  *
  * Every row is signed with `NGDPBASE_CREDENTIALS_KEY` (the instance `.env`).
@@ -40,7 +40,7 @@ export interface CredentialRecord {
     kind: CredentialKind;
     /** What identifies it within its kind: a passkey's credential id, an address, a device token's hash, an outside identity's `iss#sub`. */
     subject: string;
-    /** Kind-specific: a public key and counter, or empty (an encrypted TOTP seed once #421 is built). */
+    /** Kind-specific: a public key and counter, an encrypted TOTP seed (#421), or empty. */
     secret: string;
     /** What the person calls it — "Jim's iPhone". */
     label: string;

package/lib/src/providers/BaseCredentialsProvider.js

@@ -3,7 +3,7 @@
  *
  * Passwords stay on the user record and are never copied here (decided
  * 2026-10-02). This store holds passkeys, verified email / phone addresses
- * and known devices (TOTP seeds once #421 is built) — one row each, many per
+ * known devices and TOTP seeds (#421, encrypted) — one row each, many per
  * account.
  *
  * Every row is signed with `NGDPBASE_CREDENTIALS_KEY` (the instance `.env`).

package/lib/src/providers/BasicAttachmentProvider.d.ts

@@ -276,6 +276,15 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     private requirePagesDirectory;
     private readStoreIndex;
     private writeStoreIndex;
+    private storeRenumberedFile;
+    /**
+     * The ids a takeout import last gave the store's files that could not keep
+     * their own (#2188), as takeout id → id here. Kept apart from the index, so
+     * it outlives a delete of the file. Ids only.
+     */
+    readStoreRenumbered(location: StoreFileLocation): Promise<Map<string, string>>;
+    /** Adds `pairs` (takeout id → id here) to {@link readStoreRenumbered}'s; a later pair for an id replaces the earlier. */
+    noteStoreRenumbered(location: StoreFileLocation, pairs: ReadonlyMap<string, string>): Promise<void>;
     storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: StoreFileInput): Promise<StoreFileEntry>;
     getFileInStore(location: StoreFileLocation, id: string): Promise<{
         entry: StoreFileEntry;

package/lib/src/providers/FileCredentialsProvider.js

@@ -9,7 +9,7 @@
  *   missing or wrong is reported and can never sign anyone in; it is kept in
  *   quarantine and written back unchanged (#1633), so a lost key costs no
  *   data. `scripts/retrust-credentials.ts` re-signs them on purpose.
- * - Nothing here is a password hash. Public keys, (when TOTP is built, #421, encrypted seeds) and token
+ * - Nothing here is a password hash. Public keys, encrypted TOTP seeds (#421) and token
  *   hashes are low value to a reader; a writer is what signing stops.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';