@jwilleke/ngdpbase-types 5.20.0 → 5.22.0

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

@@ -0,0 +1,58 @@
+/**
+ * The contacts door's one decision and its one record (#1930).
+ *
+ * PersonManager and OrganizationManager are the enforcement points for
+ * contacts. Both ask the PDP the same two questions with the caller's
+ * context: `contact-read` to list, search or view, `contact-manage` to
+ * create, change, delete or link; and both record each change as the
+ * `contact-manage` audit event. That rule lives here once, so the two doors
+ * cannot drift (operator, 2026-10-20).
+ *
+ * A refusal is thrown as {@link ContactRefusedError}, carrying the decision.
+ * A route turns it into the answer with `ApiContext.enforceDeny(err.permission,
+ * err.decision)`, the one place a refusal is shaped (#1431); the door never
+ * builds an HTTP answer itself.
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+import type { CorePermission } from '../security/permissions.generated.js';
+import type { Decision } from '../types/Policy.js';
+type EngineLike = {
+    getManager: <T = unknown>(name: string) => T | null | undefined;
+};
+/** What a contacts door asks: `read` to list, search or view; `manage` to change. */
+export declare const CONTACT_PERMISSION: {
+    readonly read: "contact-read";
+    readonly manage: "contact-manage";
+};
+/** A contacts door said no. `permission` is what was refused; `decision` is the PDP's answer. */
+export declare class ContactRefusedError extends Error {
+    readonly permission: string;
+    readonly decision: Decision;
+    constructor(permission: string, decision: Decision);
+}
+/**
+ * Throws {@link ContactRefusedError} unless `ctx` may do `kind` (`read` asks
+ * `contact-read`, `manage` asks `contact-manage`), and each of `also` (a link
+ * to an account also asks `user-edit`). A missing context or decision point
+ * refuses: closed, never open.
+ */
+export declare function requireContactPermission(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, also?: readonly CorePermission[]): Promise<void>;
+/** What a contacts record says was done. Names fields, never their values. */
+export interface ContactChange {
+    kind: 'person' | 'organization';
+    operation: 'create' | 'update' | 'delete' | 'link';
+    id: string;
+    fields?: string[];
+    /** For a link: the account joined to the person. */
+    account?: string;
+    /** For a link: how it was confirmed, `admin` or `email`. */
+    via?: 'admin' | 'email';
+}
+/**
+ * Record a contacts change as `contact-manage`, under the caller's context.
+ * `continue`: a lost record is counted, the change stands. A system context
+ * goes through `recordSystemAction`, so the bootstrap admin's person, made
+ * before the audit sink is up, is recorded once it is.
+ */
+export declare function recordContactChange(engine: EngineLike, ctx: ActorContext, change: ContactChange): Promise<void>;
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export declare const DATABASE_KEY_ENV = "NGDPBASE_DATABASE_KEY";

package/lib/src/utils/databaseKey.js

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';

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

@@ -0,0 +1,78 @@
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from '../managers/BaseManager.js';
+import { siteRestoreFile, type PartOutcome } from './siteRestore.js';
+/** A folder part's `data` in the backup document. */
+export interface DirectoryBackupData {
+    format: 1;
+    /** The archive beside the document: `<stem>.<part>.tar`, or `.tar.enc` when encrypted. */
+    archive: string;
+    files: number;
+    bytes: number;
+    /** `backupKeyFingerprint()` of the key the archive is encrypted under; absent when it is not encrypted. */
+    keyFingerprint?: string;
+}
+/** Whether `name` is a bare archive name in the backup directory, never a path. */
+export declare function isArchiveName(name: unknown): name is string;
+/**
+ * The name and key for one archive of a backup: encrypted under the backup
+ * key when it is set (#1561), plain otherwise. BackupManager says, once per
+ * backup, that a backup without the key is not encrypted.
+ */
+export declare function archiveTarget(stem: string, part: string): {
+    archive: string;
+    backupKey?: string;
+    keyFingerprint?: string;
+};
+/**
+ * The key to read an archive of a backup with, checked against the
+ * fingerprint the backup recorded: a backup made under another key is
+ * refused before anything is staged. None for a backup that was not
+ * encrypted, which is then read as the plain archive it says it is.
+ */
+export declare function archiveReadKey(manager: string, data: {
+    keyFingerprint?: string;
+}): string | undefined;
+/**
+ * Back the folder up beside the document BackupManager is writing. Throws
+ * outside BackupManager: the files go beside a document, never into it.
+ * `exclude` leaves out a path relative to the folder (posix form).
+ */
+export declare function backupDirectoryPart(manager: string, part: string, folder: string | null, options?: ManagerBackupOptions, extra?: {
+    exclude?: (relative: string) => boolean;
+}): Promise<BackupData>;
+/**
+ * Stage the folder from a backup for the next start: the archive is
+ * extracted to `<folder>.staged`, and the swap recorded in the site restore.
+ * Throws — staging nothing — outside a site restore, for a backup without
+ * this part, or for an archive that is missing, unsafe, or under another key.
+ */
+export declare function stageDirectoryPart(manager: string, folder: string | null, backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+/**
+ * Put a staged restore of the folder in place, at start, before the manager
+ * reads it. Loud when something was staged but not applied.
+ */
+export declare function applyDirectoryPartAtStart(manager: string, folder: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;
+/**
+ * Back one file up beside the document, encrypted under the backup key, as
+ * `<stem>.<part>.tar.enc`. With `requireKey` and no key the file is left out:
+ * `data` is null and a warning says why, so BackupManager reports the backup
+ * incomplete (#1876: the credentials store is never in a backup unencrypted).
+ */
+export declare function backupFilePart(manager: string, part: string, file: string | null, options: ManagerBackupOptions | undefined, { requireKey, what }: {
+    requireKey: boolean;
+    what: string;
+}): Promise<{
+    data: DirectoryBackupData | null;
+    warnings: string[];
+    note?: string;
+}>;
+/**
+ * Stage one file from a backup as `<file>.staged`, and record the swap. When
+ * the file was absent at backup time the archive holds nothing, and
+ * `whenAbsent` is staged in its place (an empty store), so the restore still
+ * puts the site back as it was.
+ */
+export declare function stageFilePart(manager: string, file: string, data: DirectoryBackupData, options: ManagerRestoreOptions | undefined, { whenAbsent }: {
+    whenAbsent: string;
+}): Promise<void>;
+/** Put a staged restore of one file in place, at start, before the manager reads it. */
+export declare function applyFilePartAtStart(manager: string, file: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;

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

@@ -0,0 +1,20 @@
+/**
+ * emailForLog — the one way an email address reaches the server log (#1916).
+ *
+ * Rule (operator, 2026-10-20): a full email address never reaches the server
+ * log. A log line names the address's domain only. Audit records are not the
+ * server log and keep full addresses; do not use these helpers on them.
+ */
+/**
+ * The domain(s) of one address or a comma-separated list, lower-cased:
+ * `"Bob <bob@Example.org>, ann@x.io"` → `"example.org,x.io"`. A value
+ * without an `@` (or an empty one) reads as `unknown`.
+ */
+export declare function emailDomain(to: string | null | undefined): string;
+/**
+ * Any address inside free text (an SMTP error often quotes the rejected one)
+ * cut to its domain: `bob@example.org` → `…@example.org`.
+ */
+export declare function redactEmailAddresses(text: string): string;
+/** An error's message, with any address in it cut to its domain. */
+export declare function errorForLog(err: unknown): string;

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

@@ -0,0 +1,153 @@
+/**
+ * Maintenance mode: the one owner (#1906), and the settings it reads (#1147).
+ *
+ * {@link MaintenanceState} (at the end of this file) is the door every manager
+ * uses to put the site in maintenance mode. {@link resolveMaintenanceState}
+ * reads the administrator's settings for it from configuration.
+ *
+ * #1147, the history behind the settings reader:
+ *
+ * One switch, one state. Before this module, maintenance mode had two readers
+ * on two different sources and the admin toggle wrote to only one of them:
+ *
+ *   - the gate middleware read `engine.config.features.maintenance`, an
+ *     in-memory object that configuration never populates — `Engine.initialize`
+ *     will not overwrite `this.config` once set (`core/Engine.ts:63`), and the
+ *     constructor sets it to `{}`, so it stayed empty for the process lifetime
+ *   - `PolicyInformationPoint.checkContextRestrictions` read the documented keys through
+ *     `ConfigurationManager`
+ *
+ * So the shipped `ngdpbase.features.maintenance.enabled` key did not gate the
+ * site, the toggle did not survive a restart, and the two halves could
+ * disagree at runtime — the gate serving traffic normally while the ACL
+ * evaluator denied on maintenance grounds, or the reverse.
+ *
+ * Every reader now resolves through here, which is what makes "one switch, one
+ * state" provable rather than asserted.
+ */
+/** Configuration read function, matching `ConfigurationManager.getProperty`. */
+export type ReadProperty = (key: string, fallback: unknown) => unknown;
+/** The administrator's maintenance settings, as configured. */
+export interface MaintenanceSettings {
+    /** Whether the admin switch was left on: the persisted record of {@link ADMIN_SWITCH_REASON}. */
+    enabled: boolean;
+    /** Whether administrators may still reach the instance while it is closed. */
+    allowAdmins: boolean;
+    /** Shown on the maintenance page. Never empty. */
+    message: string;
+    /** Operator-supplied estimate, or null when none is configured. */
+    estimatedDuration: string | null;
+}
+export declare const MAINTENANCE_ENABLED_KEY = "ngdpbase.features.maintenance.enabled";
+export declare const MAINTENANCE_ALLOW_ADMINS_KEY = "ngdpbase.features.maintenance.allow-admins";
+export declare const MAINTENANCE_MESSAGE_KEY = "ngdpbase.features.maintenance.message";
+export declare const MAINTENANCE_DURATION_KEY = "ngdpbase.features.maintenance.estimated-duration";
+/**
+ * Read the administrator's maintenance settings from configuration.
+ *
+ * Read when asked rather than cached at boot, so a changed message, estimate
+ * or allow-admins applies at once. Whether the site IS in maintenance mode is
+ * {@link MaintenanceState}'s, not this: `enabled` here is only the admin
+ * switch's persisted record (#1906).
+ */
+export declare function resolveMaintenanceState(get: ReadProperty): MaintenanceSettings;
+/**
+ * #1883's key, retired by #1906. Still read when a site set it, so an instance
+ * that wrote its own outage wording for v5.20.0 keeps it — but only while the
+ * site has not set {@link MAINTENANCE_MESSAGE_KEY} itself. No shipped default.
+ */
+export declare const LEGACY_MESSAGE_KEY = "ngdpbase.managers.addons-manager.site-critical.public-message";
+/**
+ * Why the admin switch holds the site in maintenance mode: the one reason an
+ * administrator enters and leaves, through the toggle on the admin dashboard.
+ */
+export declare const ADMIN_SWITCH_REASON = "An administrator turned maintenance mode on (Admin Dashboard \u2192 Enable Maintenance; ngdpbase.features.maintenance.enabled).";
+/** What a manager may say when it puts the site in maintenance mode. */
+export interface EnterOptions {
+    /** What visitors are told, in place of the configured message. */
+    message?: string;
+    /** What visitors are told about how long, in place of the configured estimate. */
+    estimatedDuration?: string;
+    /**
+     * Whether administrators may use the whole site while this reason holds.
+     * False (the default) for a failure: everyone, administrators included, gets
+     * only `/admin`, `/login` and `/logout`, because the rest of the site cannot
+     * be trusted to work. True only for the admin switch, where nothing is broken.
+     */
+    adminsMayEnter?: boolean;
+}
+/**
+ * The configuration reads the visitor view needs — `ConfigurationManager`'s
+ * own methods, so callers pass the manager itself. `getCustomProperty` tells
+ * "the site set this" from "this is the shipped default", which decides
+ * whether the legacy key may still speak.
+ */
+export interface MaintenanceConfig {
+    getProperty(key: string, fallback: unknown): unknown;
+    getCustomProperty?(key: string): unknown;
+}
+/** What a visitor is shown while the site is in maintenance mode. It carries no reason. */
+export interface MaintenanceVisitorView {
+    message: string;
+    estimatedDuration: string | null;
+    /** Whether a signed-in administrator may use the whole site. */
+    adminsMayEnter: boolean;
+}
+/**
+ * Whether the site is in maintenance mode, and why (#1906, operator 2026-10-19).
+ *
+ * The one door. Whatever needs the site closed calls {@link enter} with a
+ * reason for administrators and, if it has one, its own message for visitors;
+ * {@link leave} reopens the site when that reason clears. AuditManager
+ * (refuse-boot), AddonsManager (a site-critical add-on that did not load),
+ * DatabaseManager (the application database cannot be opened), the boot-time
+ * configuration checks in `app.ts` (TLS files, egress ranges) and the admin
+ * toggle all go through here. `engine.blockConfiguration` is retired.
+ *
+ * __Where the state lives.__ One instance per Engine, created in its
+ * constructor (`engine.maintenance`), in memory. Not in configuration: the
+ * boot paths call `enter` while managers are still initialising —
+ * DatabaseManager before most of the others, AuditManager before the
+ * notification layer — and a failure that is only true for this run must not
+ * be written into the operator's file, where it would outlive the failure.
+ * Not a module global: each Engine, and so each test, has its own.
+ *
+ * The admin switch is the one reason that must survive a restart (#1147), so
+ * the toggle also persists `ngdpbase.features.maintenance.enabled`, and
+ * {@link restoreSwitch} enters it again at boot. That key is the reason's
+ * record; nothing reads it to decide whether the site is open.
+ *
+ * Reasons are for administrators only: the log, the admin dashboard, and the
+ * notifications the managers send. Visitors, and `/health/readiness`, get
+ * {@link visitorView}, which carries none.
+ */
+export declare class MaintenanceState {
+    private readonly entries;
+    /** Put the site in maintenance mode for `reason`. Entering a held reason again replaces its options. */
+    enter(reason: string, options?: EnterOptions): void;
+    /** Clear `reason`. The site reopens when no reason is left. False when it was not held. */
+    leave(reason: string): boolean;
+    /** Whether any reason holds the site in maintenance mode. */
+    isOn(): boolean;
+    /** Whether `reason` currently holds it. */
+    has(reason: string): boolean;
+    /** Every reason, in the order entered. For administrators only. */
+    reasons(): readonly string[];
+    /**
+     * Whether a reason holds that keeps everyone, administrators included, to
+     * `/admin`, `/login` and `/logout`: a failure, rather than the admin switch.
+     */
+    isClosedToAdmins(): boolean;
+    /** Enter the admin switch again when the configuration says it was left on (#1147). */
+    restoreSwitch(config: MaintenanceConfig | null | undefined): void;
+    /**
+     * What visitors see; null when the site is open.
+     *
+     * The message is the first reason's own, when a manager passed one; else
+     * `ngdpbase.features.maintenance.message` as the site set it; else the
+     * retired {@link LEGACY_MESSAGE_KEY}, when the site set that; else the
+     * shipped message. The estimate: the first reason's own, else
+     * `ngdpbase.features.maintenance.estimated-duration`, else none.
+     */
+    visitorView(config: MaintenanceConfig | null | undefined): MaintenanceVisitorView | null;
+}

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

@@ -416,10 +416,15 @@ export declare function resolveManagerFetch(spec: string | undefined, context: {
     };
     userContext?: unknown;
 }): Promise<ManagerFetchResult>;
-/** One choice in a form's dropdown: the value submitted, and the text shown. */
+/**
+ * One choice in a form's dropdown or checklist: the value submitted, the text
+ * shown, and optionally what it is worth in whole minor units (cents), which a
+ * checklist adds up as boxes are ticked (#1904).
+ */
 export interface FormOption {
     value: string;
     label: string;
+    amount?: number;
 }
 /** Outcome of resolveManagerOptions; the statuses mean what they mean for resolveManagerFetch. */
 export type ManagerOptionsResult = {

package/lib/src/utils/pluginFormatters.js

@@ -676,9 +676,12 @@ function toFormOptionList(value) {
             options.push({ value: item, label: item });
         }
         else if (item && typeof item === 'object') {
-            const { value: v, label } = item;
+            const { value: v, label, amount } = item;
             if ((typeof v === 'string' || typeof v === 'number') && String(v) !== '') {
-                options.push({ value: String(v), label: typeof label === 'string' && label !== '' ? label : String(v) });
+                const option = { value: String(v), label: typeof label === 'string' && label !== '' ? label : String(v) };
+                if (typeof amount === 'number' && Number.isSafeInteger(amount))
+                    option.amount = amount;
+                options.push(option);
             }
         }
     }

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

@@ -55,7 +55,7 @@ export type StoreTakeout = {
  * Returns an empty file list when the store does not exist, so a caller can ask
  * about a store without first proving it is there.
  */
-export declare function collectStore(pagesDirectory: string, owner: string, store: string, layout?: PrivateStoreLayoutOverrides): Promise<StoreTakeout>;
+export declare function collectStore(pagesDirectory: string, owner: string, store: string, layout?: PrivateStoreLayoutOverrides, skip?: (relativeToStore: string) => boolean): Promise<StoreTakeout>;
 /** The store ids a user has on disk, in directory order. */
 export declare function listStoreIds(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<string[]>;
 /** The users who have a private directory on disk, in directory order. */
@@ -68,7 +68,7 @@ export declare function listPrivateOwners(pagesDirectory: string, layout?: Priva
  * This is the unit both callers work in — an instance backup asks for it once
  * per owner, and a user's own download asks for it once, for themselves.
  */
-export declare function collectUser(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<{
+export declare function collectUser(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides, skip?: (relativeToStore: string) => boolean): Promise<{
     owner: string;
     userFiles: StoreFile[];
     stores: StoreTakeout[];

package/lib/src/utils/redactSecrets.js

@@ -37,7 +37,8 @@
  * {@link refreshRedactedSecrets} and log them themselves.
  */
 import { format } from 'winston';
-import { secretKeys } from './sensitiveValues.js';
+import { secretKeys, secretValuesBelow, valueLevels } from './sensitiveValues.js';
+import { keyOfEntry } from './configPaths.js';
 /**
  * Values shorter than this are never redacted.
  *
@@ -88,27 +89,46 @@ export function refreshRedactedSecrets(configManager) {
         redactions = [];
         return { active: 0, skipped };
     }
-    const keys = secretKeys((k, d) => configManager.getProperty(k, d));
+    const read = (k, d) => configManager.getProperty(k, d);
+    const keys = secretKeys(read);
     const seen = new Set();
     const next = [];
-    for (const rawKey of keys) {
-        if (typeof rawKey !== 'string')
-            continue;
-        const key = rawKey.trim();
-        if (key === '')
-            continue;
-        const value = configManager.getProperty(key, undefined);
+    const take = (key, value) => {
         const reason = rejectionReason(value);
         if (reason) {
             skipped.push({ key, reason });
-            continue;
+            return;
         }
         const literal = value.trim();
         // Two keys holding the same value redact once; the first key names it.
         if (seen.has(literal))
-            continue;
+            return;
         seen.add(literal);
         next.push({ key, value: literal });
+    };
+    // #1889: an entry that names a path inside a key's value (with or without
+    // a `*`) is redacted by each value it finds there, named by its full path.
+    const inside = new Set();
+    for (const rawKey of keys) {
+        if (typeof rawKey !== 'string')
+            continue;
+        const key = rawKey.trim();
+        if (key === '')
+            continue;
+        const value = configManager.getProperty(key, undefined);
+        if (value === undefined) {
+            const parent = keyOfEntry(key, (k) => configManager.getProperty(k, undefined) !== undefined);
+            if (parent) {
+                inside.add(parent);
+                continue;
+            }
+        }
+        take(key, value);
+    }
+    const levels = valueLevels(read);
+    for (const parent of inside) {
+        for (const { path, value } of secretValuesBelow(parent, configManager.getProperty(parent, undefined), levels))
+            take(path, value);
     }
     // Longest first: where one secret contains another, the longer must be
     // struck first or the shorter leaves a mangled remainder of the longer.

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

@@ -15,6 +15,13 @@
  * hides secret-looking fields nested inside an object value (an OIDC client's
  * `client_secret` inside `oidc-auth-server.clients`).
  *
+ * An entry may also name something inside a key's value by its path (#1889):
+ * `ngdpbase.addons.accounting.accounts.*.account-number`, where `*` stands for
+ * any one map key (or list index). It hides what sits there, at the entry's
+ * level, wherever a value is shown, except a bare `$NAME` reference, which is
+ * a pointer to the environment, not the secret. The paths are walked by
+ * `utils/configPaths.ts`, the same walk that resolves `$NAME` inside a value.
+ *
  * Hidden values are replaced on the server, before any HTML is built: they
  * never reach a page, its source or the parse cache.
  *
@@ -31,15 +38,31 @@ export interface ValueViewer {
 }
 /** Whether a key or field name looks like a secret (the backstop's test; also `npm run lint:sensitive`). */
 export declare function looksSecret(name: string): boolean;
+/**
+ * What an administrator's screen, a log line and an audit record may hold:
+ * sensitive values, never secrets. Secrets there are revealed one key at a
+ * time, on demand (`secret-reveal`).
+ */
+export declare const NO_SECRETS: ValueViewer;
 /** What a hidden value is shown as. */
 export declare const HIDDEN = "(hidden)";
 type Read = (key: string, fallback: unknown) => unknown;
 /**
  * The declared levels: the legacy list's keys as `secret`, then the new map
  * (`"secret"`, `"sensitive"`, `true` = secret; `false` / `null` removes an
- * entry, so an instance can override a shipped one).
+ * entry, so an instance can override a shipped one). An entry that is not a
+ * well-formed key or path (#1889: an empty segment, a `*` inside a segment, or
+ * a `*` before `ngdpbase.<category>`) is no entry, as a level that is none of
+ * these is no entry; {@link sensitiveValueProblems} names both.
  */
 export declare function valueLevels(read: Read): Map<string, ValueLevel>;
+/**
+ * What is wrong with the declared entries, one line each (#1889): an entry
+ * that is not a well-formed key or path, or a level that is none of
+ * `"secret"`, `"sensitive"`, `true`, `false`, `null`. {@link valueLevels}
+ * drops each such entry; the engine warns at boot.
+ */
+export declare function sensitiveValueProblems(read: Read): string[];
 /** The keys declared `secret`: what logs, the audit log and the admin screen never print. */
 export declare function secretKeys(read: Read): string[];
 /**
@@ -52,8 +75,31 @@ export declare function levelOf(key: string, levels: Map<string, ValueLevel>, va
 /** Whether the legacy list is still set (to warn at boot). */
 export declare function usesLegacyName(read: Read): boolean;
 /**
- * The value a viewer may see for a key: itself, or `HIDDEN`. An empty value
- * is shown as it is — "not set" reveals nothing.
+ * A key's value with what its path entries name hidden from this viewer
+ * (#1889). An empty value, and a bare `$NAME` reference, are kept: neither is
+ * the secret. The key's own level is {@link shownValue}'s business.
+ */
+export declare function hideDeclaredPaths(key: string, value: unknown, levels: Map<string, ValueLevel>, viewer: ValueViewer): unknown;
+/**
+ * The strings (and numbers, as text) a key's secret path entries name inside
+ * its value, each with its full path (#1889): what log redaction strikes.
+ * Everything under a named map or list counts.
+ */
+export declare function secretValuesBelow(key: string, value: unknown, levels: Map<string, ValueLevel>): Array<{
+    path: string;
+    value: string;
+}>;
+/**
+ * A value submitted from a screen that showed it with paths hidden, with each
+ * `HIDDEN` placeholder at a declared path put back to the stored value there
+ * (#1889). Without this, saving an edit to an accounts map would write the
+ * placeholder over every account number.
+ */
+export declare function keepHiddenValues(key: string, submitted: unknown, stored: unknown, levels: Map<string, ValueLevel>): unknown;
+/**
+ * The value a viewer may see for a key: itself, or `HIDDEN`; inside it, what
+ * its path entries name is hidden as well (#1889). An empty value is shown as
+ * it is: "not set" reveals nothing.
  */
 export declare function shownValue(key: string, value: unknown, levels: Map<string, ValueLevel>, viewer: ValueViewer): unknown;
 export {};