@jwilleke/ngdpbase-types 5.19.0 → 5.21.0

package/lib/src/utils/addonConfigLayer.js

@@ -40,6 +40,17 @@
  * never merged into the configuration: DatabaseManager reads the declarations
  * from here, so the operator's file cannot change one. An invalid declaration
  * stops its addon loading, as a refused system-category does.
+ *
+ * A third, `ngdpbase.addons.<slug>.site-critical` (#1883): whether a failure of
+ * the addon to load puts the whole site in maintenance mode. Read from the
+ * addon's own file and from the operator's, which wins either way, and kept
+ * apart from the merge so a refused addon's value is still known. A value that
+ * is not exactly `true` or `false` refuses the addon and counts as `true`.
+ *
+ * A fourth, `ngdpbase.config.sensitive-values` (#1889): an enabled addon may
+ * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
+ * (paths inside its values included). An entry for any other key refuses the
+ * addon, since it could unhide core's or another addon's secret.
  */
 import fs from 'fs';
 import path from 'path';
@@ -47,6 +58,7 @@ import { isDeepStrictEqual } from 'util';
 import { configFilePaths, deepMergeConfigs, deepMergeObjects, instanceDataFolder, isPlainObject, readConfigFilesSync } from './configFiles.js';
 import { configuredInstallSlugs, findNodeModulesDir, installedAddonsDir, matchNpmPackageDirs, resolveAddonSlug, splitAddonsPath } from './addonsPathResolver.js';
 import { lockedAddonDirsSync } from './addonLock.js';
+import { LEGACY_SECRET_KEYS_KEY, SENSITIVE_VALUES_KEY } from './sensitiveValues.js';
 import { parsePrivatestore } from './privateStorePath.js';
 import { OWNER_DECIDED_FIELDS, SYSTEM_CATEGORY_KEY, systemCategoryValueProblems } from './systemCategoryRules.js';
 import { addonDatabaseKey, addonDatabaseKeySlug, addonDatabaseProblems } from './addonDatabaseRules.js';
@@ -127,6 +139,10 @@ export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = in
     }
     return out;
 }
+/** How a problem line names an addon; AddonsManager matches it to fold a refusal into its load-failure notice (#1883). */
+export function addonProblemSubject(slug, enabled) {
+    return `add-on '${slug}'${enabled ? '' : ' (turned off)'}`;
+}
 function vaultIdOf(entry) {
     return parsePrivatestore(entry?.storageLocation?.privatestore)?.vaultId;
 }
@@ -154,7 +170,7 @@ function addonCategoryLayer(shipped, custom, addons) {
         const declared = addon.defaults[SYSTEM_CATEGORY_KEY];
         if (declared === undefined)
             continue;
-        const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+        const who = addonProblemSubject(addon.slug, addon.enabled);
         if (!isPlainObject(declared)) {
             const reason = `${SYSTEM_CATEGORY_KEY} must be a map of entries`;
             layer.problems.push(`${who}: ${reason}; it is refused and the add-on is not loaded`);
@@ -246,7 +262,7 @@ export function addonDatabaseLayer(addons, custom) {
             }
         }
         if (reasons.length > 0) {
-            const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+            const who = addonProblemSubject(addon.slug, addon.enabled);
             layer.problems.push(`${who}: its database declaration is refused (${reasons.join('; ')}); the add-on is not loaded`);
             layer.refused.set(addon.slug, `its database declaration was refused: ${reasons.join('; ')}`);
             continue;
@@ -262,6 +278,80 @@ export function addonDatabaseLayer(addons, custom) {
     }
     return layer;
 }
+/** Every entry an addon's file names in a sensitive-values map or the legacy list, whatever its level. */
+function sensitiveEntriesOf(defaults) {
+    const names = [];
+    for (const listKey of [SENSITIVE_VALUES_KEY, LEGACY_SECRET_KEYS_KEY]) {
+        const declared = defaults[listKey];
+        if (Array.isArray(declared))
+            names.push(...declared.filter((v) => typeof v === 'string'));
+        else if (isPlainObject(declared))
+            names.push(...Object.keys(declared));
+    }
+    return names;
+}
+/**
+ * Which values an addon may classify (#1889): its own, `ngdpbase.addons.<slug>`
+ * and anything under it, top-level keys and paths alike. An entry for core's
+ * keys or another addon's could unhide them (`false`, or `sensitive` for a
+ * `secret`), so it refuses the addon, as a database declaration under another
+ * slug does (#1860): it is not loaded and none of its keys apply. Only an
+ * enabled addon's entries reach the merge, so only an enabled addon is checked.
+ */
+export function addonSensitiveValuesLayer(addons) {
+    const layer = { refused: new Map(), problems: [] };
+    for (const addon of addons) {
+        if (!addon.enabled)
+            continue;
+        const own = `ngdpbase.addons.${addon.slug}`;
+        const foreign = sensitiveEntriesOf(addon.defaults).filter((entry) => entry.trim() !== own && !entry.trim().startsWith(`${own}.`));
+        if (foreign.length === 0)
+            continue;
+        const reason = `its sensitive-values entries ${foreign.map((e) => `'${e}'`).join(', ')} are not its own; an add-on classifies only ${own} and what is under it`;
+        layer.refused.set(addon.slug, reason);
+        layer.problems.push(`${addonProblemSubject(addon.slug, addon.enabled)}: ${reason}; the add-on is not loaded`);
+    }
+    return layer;
+}
+/** The configuration key that makes an addon site-critical (#1883). */
+export function addonSiteCriticalKey(slug) {
+    return `ngdpbase.addons.${slug}.site-critical`;
+}
+/**
+ * Which addons are site-critical (#1883): the operator's value if the
+ * operator's file sets one, else the addon's own (only under its own slug),
+ * else not. The operator's file wins in both directions, as for every addon
+ * key. The value is exactly `true` or `false`; anything else (the string
+ * `"true"` included) refuses the addon and counts as site-critical, so a
+ * mistyped value fails closed. `custom` keys for an addon with no file, or
+ * one that is not installed, count too.
+ */
+export function addonSiteCriticalLayer(addons, custom) {
+    const layer = { siteCritical: new Map(), refused: new Map(), problems: [] };
+    const take = (slug, enabled, own) => {
+        const key = addonSiteCriticalKey(slug);
+        const fromSite = custom[key] !== undefined;
+        const value = fromSite ? custom[key] : own;
+        if (value === undefined)
+            return;
+        if (typeof value === 'boolean') {
+            layer.siteCritical.set(slug, value);
+            return;
+        }
+        const reason = `${key} must be true or false, got ${JSON.stringify(value)} in ${fromSite ? 'app-custom-config.json' : 'its config/default-config.json'}; it is treated as true`;
+        layer.siteCritical.set(slug, true);
+        layer.refused.set(slug, reason);
+        layer.problems.push(`${addonProblemSubject(slug, enabled)}: ${reason}; the add-on is not loaded`);
+    };
+    for (const addon of addons)
+        take(addon.slug, addon.enabled, addon.defaults[addonSiteCriticalKey(addon.slug)]);
+    for (const key of Object.keys(custom)) {
+        const slug = /^ngdpbase\.addons\.([^.]+)\.site-critical$/.exec(key)?.[1];
+        if (slug && !layer.siteCritical.has(slug))
+            take(slug, custom[`ngdpbase.addons.${slug}.enabled`] === true, undefined);
+    }
+    return layer;
+}
 /**
  * The owner's declaration stands (operator, 2026-09-29): for each entry an
  * addon declared, the fields in OWNER_DECIDED_FIELDS are the addon's, never
@@ -310,8 +400,11 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const customCategories = custom[SYSTEM_CATEGORY_KEY];
     const layer = addonCategoryLayer(shipped[SYSTEM_CATEGORY_KEY], customCategories, addons);
     const databaseLayer = addonDatabaseLayer(addons, custom);
+    const criticalLayer = addonSiteCriticalLayer(addons, custom);
+    const sensitiveLayer = addonSensitiveValuesLayer(addons);
+    const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of databaseLayer.refused)
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -325,14 +418,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems], refused, databases };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems], refused, databases };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,
@@ -344,12 +437,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
  * could not be read; `refused` names, by slug, each addon that must not load
  * because an entry it declares was refused, and why (#1559), or because its
  * database declaration was (#1860); `databases` is every sound database
- * declaration of every installed addon, on or off (#1860).
+ * declaration of every installed addon, on or off (#1860); `siteCritical`
+ * says, by slug, which addons put the site in maintenance mode when they fail
+ * to load (#1883).
  */
 export function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
     const base = deepMergeConfigs(shipped, custom);
     const all = discoverAddonDefaults(base, cwd, dataFolder);
-    const { merged, problems, refused, databases } = mergeWithAddonLayer(shipped, all, custom);
+    const { merged, problems, refused, databases, siteCritical } = mergeWithAddonLayer(shipped, all, custom);
     const unreadable = all
         .filter((a) => !a.enabled && a.error)
         .map((a) => `add-on '${a.slug}' (turned off): config/default-config.json could not be read (${a.error}); its system-categories and database are not known`);
@@ -359,7 +454,8 @@ export function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), data
         addons: all.filter((a) => a.enabled && !refused.has(a.slug)),
         problems: [...unreadable, ...problems],
         refused,
-        databases
+        databases,
+        siteCritical
     };
 }
 /**

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

@@ -0,0 +1,55 @@
+/**
+ * Paths inside a configuration value (#1889).
+ *
+ * A configuration key names a value; when the value is a map or a list, each
+ * thing inside it has a path below the key: its map keys and list indices, in
+ * order. `ngdpbase.addons.accounting.accounts` → `checking` → `account-number`
+ * is written `ngdpbase.addons.accounting.accounts.checking.account-number`.
+ *
+ * Two readers walk these paths, and they walk them here, the same way:
+ *
+ *   - `ConfigurationManager` resolves a bare `$NAME` environment reference
+ *     wherever it sits in a value, naming the full path when the variable is
+ *     unset;
+ *   - `sensitiveValues` hides what `ngdpbase.config.sensitive-values` names by
+ *     a path, where `*` stands for any one map key (or list index).
+ *
+ * @module utils/configPaths
+ */
+/** A bare, whole-string environment reference: `$NAME`, upper case, digits and `_`. */
+export declare const ENV_REF_PATTERN: RegExp;
+/** The variable a bare `$NAME` reference names, or null when the value is not one. */
+export declare function envRefName(value: unknown): string | null;
+/** One path segment that stands for any map key or list index. */
+export declare const WILDCARD = "*";
+/** A key and the path below it, written as configuration keys are: dot-joined. */
+export declare function pathString(key: string, below: readonly string[]): string;
+/**
+ * Visit a value and everything inside it, top first. `visit` returns a
+ * replacement for the node, or `undefined` to keep it and go inside. Copy on
+ * write: a map or list nothing inside changed is returned as itself, so a read
+ * of a value with nothing to replace allocates nothing.
+ */
+export declare function mapConfigValue(value: unknown, visit: (node: unknown, below: readonly string[]) => unknown, below?: string[]): unknown;
+/**
+ * The segments of a path entry, or null when it is not a well-formed one: no
+ * empty segment, and `*` only as a whole segment with at least two written-out
+ * segments before the first one (`ngdpbase.<category>`), since a key is never
+ * a wildcard.
+ */
+export declare function parsePathEntry(entry: string): string[] | null;
+/**
+ * Whether `entry` names something inside `key`'s value, and the path pattern
+ * below the key if so. The key is matched literally: a `*` stands only for a
+ * segment below it.
+ */
+export declare function patternBelow(entry: string, key: string): string[] | null;
+/** Whether a path below a key matches a pattern below it: same length, `*` any one segment. */
+export declare function pathMatches(pattern: readonly string[], below: readonly string[]): boolean;
+/** What sits at a path below a value, or undefined. */
+export declare function valueAt(value: unknown, below: readonly string[]): unknown;
+/**
+ * The configuration key a path entry lies inside: the longest prefix, ending
+ * before the first `*`, for which `has` is true. Null when none is set.
+ */
+export declare function keyOfEntry(entry: string, has: (key: string) => boolean): string | null;

package/lib/src/utils/configPaths.js

@@ -0,0 +1,133 @@
+/**
+ * Paths inside a configuration value (#1889).
+ *
+ * A configuration key names a value; when the value is a map or a list, each
+ * thing inside it has a path below the key: its map keys and list indices, in
+ * order. `ngdpbase.addons.accounting.accounts` → `checking` → `account-number`
+ * is written `ngdpbase.addons.accounting.accounts.checking.account-number`.
+ *
+ * Two readers walk these paths, and they walk them here, the same way:
+ *
+ *   - `ConfigurationManager` resolves a bare `$NAME` environment reference
+ *     wherever it sits in a value, naming the full path when the variable is
+ *     unset;
+ *   - `sensitiveValues` hides what `ngdpbase.config.sensitive-values` names by
+ *     a path, where `*` stands for any one map key (or list index).
+ *
+ * @module utils/configPaths
+ */
+/** A bare, whole-string environment reference: `$NAME`, upper case, digits and `_`. */
+export const ENV_REF_PATTERN = /^\$([A-Z_][A-Z0-9_]*)$/;
+/** The variable a bare `$NAME` reference names, or null when the value is not one. */
+export function envRefName(value) {
+    return typeof value === 'string' ? (ENV_REF_PATTERN.exec(value)?.[1] ?? null) : null;
+}
+/** One path segment that stands for any map key or list index. */
+export const WILDCARD = '*';
+/** A key and the path below it, written as configuration keys are: dot-joined. */
+export function pathString(key, below) {
+    return below.length === 0 ? key : `${key}.${below.join('.')}`;
+}
+/**
+ * Visit a value and everything inside it, top first. `visit` returns a
+ * replacement for the node, or `undefined` to keep it and go inside. Copy on
+ * write: a map or list nothing inside changed is returned as itself, so a read
+ * of a value with nothing to replace allocates nothing.
+ */
+export function mapConfigValue(value, visit, below = []) {
+    const replaced = visit(value, below);
+    if (replaced !== undefined)
+        return replaced;
+    if (Array.isArray(value)) {
+        let out = null;
+        for (let i = 0; i < value.length; i++) {
+            below.push(String(i));
+            const next = mapConfigValue(value[i], visit, below);
+            below.pop();
+            if (next !== value[i]) {
+                out ??= value.slice();
+                out[i] = next;
+            }
+        }
+        return out ?? value;
+    }
+    if (value !== null && typeof value === 'object') {
+        let out = null;
+        for (const [k, v] of Object.entries(value)) {
+            below.push(k);
+            const next = mapConfigValue(v, visit, below);
+            below.pop();
+            if (next !== v) {
+                out ??= { ...value };
+                out[k] = next;
+            }
+        }
+        return out ?? value;
+    }
+    return value;
+}
+/**
+ * The segments of a path entry, or null when it is not a well-formed one: no
+ * empty segment, and `*` only as a whole segment with at least two written-out
+ * segments before the first one (`ngdpbase.<category>`), since a key is never
+ * a wildcard.
+ */
+export function parsePathEntry(entry) {
+    if (typeof entry !== 'string' || entry === '')
+        return null;
+    const segments = entry.split('.');
+    if (segments.some((s) => s === '' || (s.includes(WILDCARD) && s !== WILDCARD)))
+        return null;
+    const wild = segments.indexOf(WILDCARD);
+    if (wild !== -1 && wild < 2)
+        return null;
+    return segments;
+}
+/**
+ * Whether `entry` names something inside `key`'s value, and the path pattern
+ * below the key if so. The key is matched literally: a `*` stands only for a
+ * segment below it.
+ */
+export function patternBelow(entry, key) {
+    if (!entry.startsWith(`${key}.`))
+        return null;
+    const segments = parsePathEntry(entry);
+    return segments ? segments.slice(key.split('.').length) : null;
+}
+/** Whether a path below a key matches a pattern below it: same length, `*` any one segment. */
+export function pathMatches(pattern, below) {
+    if (pattern.length !== below.length)
+        return false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] !== WILDCARD && pattern[i] !== below[i])
+            return false;
+    }
+    return true;
+}
+/** What sits at a path below a value, or undefined. */
+export function valueAt(value, below) {
+    let node = value;
+    for (const segment of below) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+}
+/**
+ * The configuration key a path entry lies inside: the longest prefix, ending
+ * before the first `*`, for which `has` is true. Null when none is set.
+ */
+export function keyOfEntry(entry, has) {
+    const segments = parsePathEntry(entry);
+    if (!segments)
+        return null;
+    const wild = segments.indexOf(WILDCARD);
+    const longest = wild === -1 ? segments.length - 1 : wild;
+    for (let n = longest; n >= 2; n--) {
+        const key = segments.slice(0, n).join('.');
+        if (has(key))
+            return key;
+    }
+    return 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/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 {};