@jwilleke/ngdpbase-types 5.20.0 → 5.22.0

package/lib/src/types/Person.d.ts

@@ -6,8 +6,9 @@
  * (where the uuid matches the v4 segment of `@id`).
  *
  * `@id` uses the urn:uuid:<v4> form because persons typically lack a
- * canonical web URL. `identifier` matches `User.username` so existing auth
- * records link cleanly to a Person.
+ * canonical web URL. `identifier` is the person's account (`User.username`)
+ * when they have one, and `person:<uuid>` when they do not (#1930) — a form
+ * no username may take (`ACCOUNTLESS_PERSON_PREFIX`, `src/utils/username.ts`).
  *
  * No embedded role-records — those live in the future person-contacts
  * addon (#602) and are folded in at JSON-LD export time.
@@ -15,6 +16,18 @@
  * @see https://schema.org/Person
  */
 import type { PostalAddress, ContactPoint } from './Organization.js';
+/**
+ * One organization a person is affiliated with (#1930): schema.org
+ * `affiliation`, with the person's role or title there when one is known.
+ * The organization is named by its `@id`; OrganizationManager lists an
+ * organization's people by reading these, so the link is stored once, here.
+ */
+export interface PersonAffiliation {
+    /** The organization's `@id`. */
+    organization: string;
+    /** The person's role or title there (schema.org `roleName`), when known. */
+    role?: string;
+}
 /**
  * Canonical Person record.
  *
@@ -26,7 +39,7 @@ export interface Person {
     '@type': 'Person';
     /** urn:uuid:<v4> */
     '@id': string;
-    /** Matches User.username so auth records link to this Person */
+    /** The account's username, or `person:<uuid>` for a person with no account (#1930). */
     identifier: string;
     /** Display name */
     name?: string;
@@ -46,6 +59,8 @@ export interface Person {
     image?: string;
     /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
     sameAs?: string[];
+    /** Organizations this person is affiliated with, each with an optional role (#1930). */
+    affiliation?: PersonAffiliation[];
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
 }
@@ -54,3 +69,12 @@ export interface Person {
  * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
+/**
+ * What a caller gives `PersonManager.create` (#1930): the person's fields.
+ * `identifier` is left out for a person with no account (one is generated);
+ * UserManager passes the account's username when it creates the person for a
+ * new account.
+ */
+export type PersonInput = PersonUpdate & {
+    identifier?: string;
+};

package/lib/src/types/PersonProvider.d.ts

@@ -18,6 +18,12 @@ export interface PersonProvider extends BaseProvider {
     getByIdentifier(identifier: string): Promise<Person | null>;
     /** Persist a new Person. Returns the stored record. */
     create(person: Person): Promise<Person>;
+    /**
+     * Write the whole record in place of the one with the same `@id` (#1930).
+     * The only write that may change `identifier`: PersonManager uses it to join
+     * a person to an account.
+     */
+    replace(person: Person): Promise<Person>;
     /** Apply a partial update by `@id`. Returns the updated record, or null if not found. */
     update(id: string, patch: PersonUpdate): Promise<Person | null>;
     /** Delete by `@id`. Returns true if a record was removed. */

package/lib/src/types/WikiEngine.d.ts

@@ -8,6 +8,7 @@ import { WikiConfig } from './Config.js';
 import type { Logger } from 'winston';
 import type { Application, Request, RequestHandler, Router, RouterOptions } from 'express';
 import type express from 'express';
+import type { MaintenanceState } from '../utils/maintenanceState.js';
 /**
  * All known manager names as a union type
  * Use with getManager() for type-safe access when combined with explicit type parameter
@@ -95,28 +96,15 @@ export interface WikiEngine {
      */
     shutdown(): Promise<void>;
     /**
-     * Record a configuration value that cannot be used (#1152).
-     *
-     * Recorded rather than thrown so `initialize()` finishes and the admin
-     * screens exist — the instance then serves maintenance mode with a route to
-     * the repair, instead of exiting and leaving the filesystem as the only way
-     * back. Only for values an administrator can fix through the admin UI; a
-     * failure of the machinery needed to serve that UI is fatal and still throws.
-     * Also a site-critical add-on that did not load (#1883, operator
-     * 2026-10-18): its fix may lie outside the UI (a key in the instance .env),
-     * and the admin notification says so.
-     */
-    blockConfiguration(reason: string, options?: {
-        publicMessage?: string;
-    }): void;
-    /** Configuration values that could not be used, in the order found (#1152). */
-    getBlockingConditions(): readonly string[];
-    /**
-     * What visitors see in place of the reasons, when a reason was recorded with
-     * a `publicMessage` (#1883: a site-critical add-on that did not load); null
-     * when every reason may be shown.
+     * Whether the site is in maintenance mode, and why (#1906): the one door.
+     * A manager that needs the site closed calls `maintenance.enter(reason,
+     * { message?, estimatedDuration? })`, and `maintenance.leave(reason)` when
+     * the reason clears. Reasons are for administrators only; visitors get
+     * `maintenance.visitorView(configManager)`. Replaces `blockConfiguration`
+     * (#1152), still recorded rather than thrown so `initialize()` finishes and
+     * `/admin`, `/login` and `/logout` stay reachable.
      */
-    getPublicBlockingMessage(): string | null;
+    readonly maintenance: MaintenanceState;
     /**
      * Get all registered manager names
      * @returns Array of manager names

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

@@ -46,6 +46,11 @@
  * 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 { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -100,6 +105,20 @@ export interface AddonDatabaseLayer {
  * file: a value there for a declaration's key is ignored, and said so.
  */
 export declare function addonDatabaseLayer(addons: readonly AddonDefaults[], custom: Record<string, unknown>): AddonDatabaseLayer;
+export interface AddonSensitiveValuesLayer {
+    /** Addons with an entry for a key that is not their own, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * 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 declare function addonSensitiveValuesLayer(addons: readonly AddonDefaults[]): AddonSensitiveValuesLayer;
 /** The configuration key that makes an addon site-critical (#1883). */
 export declare function addonSiteCriticalKey(slug: string): string;
 export interface AddonSiteCriticalLayer {

package/lib/src/utils/addonConfigLayer.js

@@ -46,6 +46,11 @@
  * 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';
@@ -53,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';
@@ -272,6 +278,41 @@ 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`;
@@ -360,9 +401,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     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, ...criticalLayer.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
@@ -376,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, ...criticalLayer.problems], refused, databases, siteCritical };
+        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, ...criticalLayer.problems], refused, databases, siteCritical };
+    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,

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

@@ -31,6 +31,30 @@ export declare function evaluateSeededAddonPage(args: {
     liveContent: string;
     storedHash: string | undefined;
 }): SeededAddonPageStatus;
+/**
+ * How a shipped item's sync status reads on an admin screen: the status words
+ * and the edit protection of Admin → Required Pages, which every screen that
+ * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`;
+ * shipped forms, #1918).
+ *
+ *  - `status` — `modified` when the live copy differs from what ships,
+ *    `current` when it is the same.
+ *  - `userModified` — edited on this site: Sync does not replace it; Force Sync
+ *    does, after a confirm.
+ */
+export interface SyncRowState {
+    status: 'current' | 'modified';
+    userModified: boolean;
+}
+/**
+ * The one mapping from `evaluateSeededAddonPage`'s answer to the admin screen's
+ * words (#1918). `userModifiedFlag` is a page's explicit `user-modified`
+ * frontmatter, which marks it edited even when the hash cannot tell.
+ *
+ * @param seedStatus - `evaluateSeededAddonPage`'s answer for the live copy
+ * @param userModifiedFlag - The live copy is explicitly marked edited
+ */
+export declare function syncRowState(seedStatus: SeededAddonPageStatus, userModifiedFlag?: boolean): SyncRowState;
 /**
  * Default edit access for a page ngdpbase ships (#971, #1411): a `general`
  * page is instance-owned and gets no stamp; any other category — system,

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

@@ -0,0 +1,21 @@
+/**
+ * Who an administrator notification goes to.
+ *
+ * __An administrator is whoever holds `admin-system`__, asked per user through
+ * the policy (#1431 7b) — never a role name. Used by every report that must
+ * reach administrators and nobody else: a damaged page (#1431 step 7) and
+ * failing outbound email (#1916).
+ *
+ * An empty answer means "nobody to tell", and the caller must then log only:
+ * an empty `targetUsers` list means ALL users in NotificationManager, which
+ * would announce an operator problem to every reader.
+ *
+ * Null when the managers needed to answer are not registered (tests, a
+ * half-booted engine) — the caller treats that like "nobody to tell".
+ */
+type EngineLike = {
+    getManager: (name: string) => unknown;
+} | null | undefined;
+/** Usernames of every user who holds `admin-system`; null when it cannot be asked. */
+export declare function administratorUsernames(engine: EngineLike): Promise<string[] | null>;
+export {};

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -36,6 +36,8 @@ export declare const AUDIT_EVENT: {
     readonly BACKUP_CREATE: "backup-create";
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE: "backup-restore";
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    readonly BACKUP_RESTORE_APPLIED: "backup-restore-applied";
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE_CANCEL: "backup-restore-cancel";
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -48,6 +50,8 @@ export declare const AUDIT_EVENT: {
     readonly CONFIG_CHANGE: "config-change";
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     readonly CONFIG_RESET: "config-reset";
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    readonly CONTACT_MANAGE: "contact-manage";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** A background job finished successfully */

package/lib/src/utils/auditEventNames.generated.js

@@ -43,6 +43,8 @@ export const AUDIT_EVENT = {
     BACKUP_CREATE: 'backup-create',
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     BACKUP_RESTORE: 'backup-restore',
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    BACKUP_RESTORE_APPLIED: 'backup-restore-applied',
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     BACKUP_RESTORE_CANCEL: 'backup-restore-cancel',
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -55,6 +57,8 @@ export const AUDIT_EVENT = {
     CONFIG_CHANGE: 'config-change',
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     CONFIG_RESET: 'config-reset',
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    CONTACT_MANAGE: 'contact-manage',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** A background job finished successfully */

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

@@ -0,0 +1,28 @@
+import { Transform } from 'node:stream';
+/** The first bytes of every encrypted backup file. */
+export declare const BACKUP_FILE_MAGIC: Buffer<ArrayBuffer>;
+/** What an encrypted backup file's name ends with. */
+export declare const ENCRYPTED_SUFFIX = ".enc";
+/** A backup file made under a different backup key than the one set now. */
+export declare class BackupKeyMismatchError extends Error {
+    readonly fileFingerprint: string;
+    readonly keyFingerprint: string;
+    constructor(fileFingerprint: string, keyFingerprint: string);
+}
+/** Whether these bytes (a file's first) are an encrypted backup file. */
+export declare function isEncryptedBackup(head: Buffer): boolean;
+/** Whether the file on disk is an encrypted backup file, read from its first bytes only. */
+export declare function fileIsEncrypted(file: string): Promise<boolean>;
+/** A stream that encrypts what is written to it under `backupKey`. */
+export declare function encryptStream(backupKey: string): Transform;
+/**
+ * A stream that decrypts an encrypted backup file written to it. Fails —
+ * naming why — on a file that is not one, a different backup key
+ * ({@link BackupKeyMismatchError}), any record that does not verify, and a
+ * file cut short or with bytes after its last record.
+ */
+export declare function decryptStream(backupKey: string): Transform;
+/** Encrypt a whole buffer (the backup document, already in memory). */
+export declare function encryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;
+/** Decrypt a whole buffer. */
+export declare function decryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;

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

@@ -0,0 +1,23 @@
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * Its own secret, not the database key: the copy that travels and the copy
+ * that stays should not fall to the same compromise. Never a config key.
+ */
+export declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export declare function backupKeyFingerprint(key: string): string;
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export declare const LEFT_OUT_FOR_NO_KEY = "NGDPBASE_BACKUP_KEY is not set, so ";
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export declare function isLeftOutForNoKey(message: string): boolean;
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export declare function currentBackupKey(): string;

package/lib/src/utils/backupKey.js

@@ -0,0 +1,37 @@
+/**
+ * The backup key (#1723, #1561, #1876): the one secret every encrypted part of
+ * a backup is made under — the database files (SQLCipher, `sqliteBackup.ts`),
+ * and the backup document, the file archives and the credentials store
+ * (`backupCrypto.ts`). One declaration here; DatabaseManager and the file
+ * parts read it from this module.
+ */
+import { createHmac } from 'node:crypto';
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * Its own secret, not the database key: the copy that travels and the copy
+ * that stays should not fall to the same compromise. Never a config key.
+ */
+export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export function backupKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
+}
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export const LEFT_OUT_FOR_NO_KEY = `${BACKUP_KEY_ENV} is not set, so `;
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export function isLeftOutForNoKey(message) {
+    return message.startsWith(LEFT_OUT_FOR_NO_KEY);
+}
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export function currentBackupKey() {
+    return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+}

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;
+}