@jwilleke/ngdpbase-types 5.19.0 → 5.21.0

package/lib/src/utils/sensitiveValues.js

@@ -15,12 +15,20 @@
  * 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.
  *
  * @module utils/sensitiveValues
  */
 import { enabledEntries } from './configFiles.js';
+import { envRefName, mapConfigValue, parsePathEntry, pathMatches, pathString, patternBelow, valueAt } from './configPaths.js';
 export const SENSITIVE_VALUES_KEY = 'ngdpbase.config.sensitive-values';
 /** The list's name before #1750; still read, with a boot warning to rename it. */
 export const LEGACY_SECRET_KEYS_KEY = 'ngdpbase.config.secret-keys';
@@ -30,34 +38,83 @@ const SECRET_NAME_PATTERN = /secret|passw(or)?d|token|credential|api[-_]?key|pri
 export function looksSecret(name) {
     return SECRET_NAME_PATTERN.test(name);
 }
+/**
+ * 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 const NO_SECRETS = Object.freeze({ sensitive: true, secret: false });
 /** What a hidden value is shown as. */
 export const HIDDEN = '(hidden)';
 /**
  * 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 function valueLevels(read) {
     const levels = new Map();
-    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})))
-        levels.set(key, 'secret');
+    const entry = (key) => (parsePathEntry(key.trim()) ? key.trim() : null);
+    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {}))) {
+        const k = entry(key);
+        if (k)
+            levels.set(k, 'secret');
+    }
     const declared = read(SENSITIVE_VALUES_KEY, {});
     if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
         for (const [key, level] of Object.entries(declared)) {
+            const k = entry(key);
+            if (!k)
+                continue;
             if (level === 'secret' || level === true)
-                levels.set(key, 'secret');
+                levels.set(k, 'secret');
             else if (level === 'sensitive')
-                levels.set(key, 'sensitive');
+                levels.set(k, 'sensitive');
             else
-                levels.delete(key);
+                levels.delete(k);
         }
     }
     else {
-        for (const key of enabledEntries(declared))
-            levels.set(key, 'secret');
+        for (const key of enabledEntries(declared)) {
+            const k = entry(key);
+            if (k)
+                levels.set(k, 'secret');
+        }
     }
     return levels;
 }
+/**
+ * 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 function sensitiveValueProblems(read) {
+    const problems = [];
+    const named = (list, key) => {
+        if (!parsePathEntry(key.trim())) {
+            problems.push(`${list}: '${key}' is not a configuration key or path (an empty segment, or a * that is not a whole segment after ngdpbase.<category>); it is ignored`);
+        }
+    };
+    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})))
+        named(LEGACY_SECRET_KEYS_KEY, key);
+    const declared = read(SENSITIVE_VALUES_KEY, {});
+    if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
+        for (const [key, level] of Object.entries(declared)) {
+            named(SENSITIVE_VALUES_KEY, key);
+            if (!(level === 'secret' || level === 'sensitive' || level === true || level === false || level === null)) {
+                problems.push(`${SENSITIVE_VALUES_KEY}: '${key}' has level ${JSON.stringify(level)}, which is not "secret" or "sensitive"; the entry is ignored`);
+            }
+        }
+    }
+    else {
+        for (const key of enabledEntries(declared))
+            named(SENSITIVE_VALUES_KEY, key);
+    }
+    return problems;
+}
 /** The keys declared `secret`: what logs, the audit log and the admin screen never print. */
 export function secretKeys(read) {
     return [...valueLevels(read)].filter(([, level]) => level === 'secret').map(([key]) => key);
@@ -91,9 +148,79 @@ function hideNestedSecrets(value) {
     }
     return value;
 }
+/** The path entries inside a key's value, as patterns below the key, with their levels. */
+function entriesBelow(key, levels) {
+    const out = [];
+    for (const [entry, level] of levels) {
+        const pattern = patternBelow(entry, key);
+        if (pattern && pattern.length > 0)
+            out.push([pattern, level]);
+    }
+    return out;
+}
+/** Whether a viewer may see a value at this level. */
+function maySee(level, viewer) {
+    return level === 'secret' ? viewer.secret : viewer.sensitive;
+}
+/**
+ * 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 function hideDeclaredPaths(key, value, levels, viewer) {
+    const hidden = entriesBelow(key, levels).filter(([, level]) => !maySee(level, viewer)).map(([pattern]) => pattern);
+    if (hidden.length === 0)
+        return value;
+    return mapConfigValue(value, (node, below) => {
+        if (below.length === 0 || !hidden.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        return node === undefined || node === null || node === '' || envRefName(node) ? node : HIDDEN;
+    });
+}
+/**
+ * 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 function secretValuesBelow(key, value, levels) {
+    const secret = entriesBelow(key, levels).filter(([, level]) => level === 'secret').map(([pattern]) => pattern);
+    const found = [];
+    if (secret.length === 0)
+        return found;
+    mapConfigValue(value, (node, below) => {
+        if (below.length === 0 || !secret.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        const at = [...below];
+        mapConfigValue(node, (leaf, under) => {
+            if (typeof leaf === 'string' || typeof leaf === 'number')
+                found.push({ path: pathString(key, [...at, ...under]), value: String(leaf) });
+            return undefined;
+        });
+        return node;
+    });
+    return found;
+}
+/**
+ * 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 function keepHiddenValues(key, submitted, stored, levels) {
+    const patterns = entriesBelow(key, levels).map(([pattern]) => pattern);
+    if (patterns.length === 0)
+        return submitted;
+    return mapConfigValue(submitted, (node, below) => {
+        if (node !== HIDDEN || !patterns.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        const kept = valueAt(stored, below);
+        return kept === undefined ? node : kept;
+    });
+}
 /**
- * The value a viewer may see for a key: itself, or `HIDDEN`. An empty value
- * is shown as it is — "not set" reveals nothing.
+ * 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 function shownValue(key, value, levels, viewer) {
     const empty = value === undefined || value === null || value === '';
@@ -102,5 +229,6 @@ export function shownValue(key, value, levels, viewer) {
         return empty ? value : HIDDEN;
     if (level === 'sensitive' && !viewer.sensitive)
         return empty ? value : HIDDEN;
-    return viewer.secret ? value : hideNestedSecrets(value);
+    const shown = hideDeclaredPaths(key, value, levels, viewer);
+    return viewer.secret ? shown : hideNestedSecrets(shown);
 }

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

@@ -0,0 +1,65 @@
+/**
+ * What the initialisation gate serves, and when (#1152).
+ *
+ * `app.ts` used to treat every initialisation failure the same way:
+ * `process.exit(1)`. A mistyped CIDR and an unreadable data directory produced
+ * the identical outcome — a process that is gone, and an operator whose only
+ * route back is the filesystem. Under a supervisor it is worse than useless: a
+ * process that exits on a bad config value restarts, fails identically, and
+ * restarts again, and nothing in that loop ever reaches the admin UI.
+ *
+ * __The test is not severity.__ A malformed deny rule is serious, and the
+ * instance should stop serving because of it. The question is whether stopping
+ * the *process* helps, and it only helps when the process cannot offer a way
+ * out.
+ *
+ * See D9 to D13 of docs/security-posture.md.
+ */
+/**
+ * Paths served in every state, so the maintenance page can render itself.
+ *
+ * Assets only. Adding a route here would open it during `starting` too, when
+ * the managers behind it are not up.
+ */
+export declare const STARTUP_BYPASS_PATHS: readonly ["/css", "/js", "/images", "/themes", "/addons"];
+export type GateDecision = 'serve' | 'block';
+/**
+ * What the initialisation gate should do with a request.
+ *
+ * The server either is `engineReady` or it is not. What decides the third
+ * behaviour is not a third readiness value but a second, independent fact:
+ * whether the engine finished and a configuration value is unusable. Both are
+ * passed in, so the impossible combination — ready AND blocked — simply never
+ * arises at the call site rather than being modelled away.
+ */
+export declare function gateDecision(engineReady: boolean, blocked: boolean, path: string): GateDecision;
+/**
+ * The message shown on the maintenance page and logged at boot.
+ *
+ * Every reason at once, rather than the first: an operator who fixes one and
+ * restarts into the next has been made to do the work twice.
+ */
+export declare function describeBlocked(reasons: readonly string[]): string;
+/**
+ * What a visitor is told about a blocked instance: on the maintenance page and
+ * in `/health/readiness`, both served without sign-in (#1883).
+ *
+ * Every reason, as {@link describeBlocked} words them, unless one was recorded
+ * for administrators only (a site-critical add-on that did not load): then
+ * only `publicMessage`, and no reason at all — not even the ones that could be
+ * shown, since one detail beside a vague notice still says what failed.
+ * Administrators get the reasons in the log and the admin notification.
+ */
+export declare function blockedForVisitors(reasons: readonly string[], publicMessage: string | null): {
+    message: string;
+    detail: readonly string[];
+};
+/**
+ * #1883: what visitors see while a failure for administrators only holds the
+ * site in maintenance mode — a site-critical add-on that did not load, or an
+ * application database that cannot be opened safely (#1892). Empty leaves
+ * only the page's heading.
+ */
+export declare const SITE_CRITICAL_PUBLIC_MESSAGE_KEY = "ngdpbase.managers.addons-manager.site-critical.public-message";
+/** The configured public message ({@link SITE_CRITICAL_PUBLIC_MESSAGE_KEY}); '' when unset or not a string. */
+export declare function sitePublicMessage(getProperty: ((key: string, fallback: unknown) => unknown) | undefined): string;

package/lib/src/utils/startupState.js

@@ -0,0 +1,115 @@
+/**
+ * What the initialisation gate serves, and when (#1152).
+ *
+ * `app.ts` used to treat every initialisation failure the same way:
+ * `process.exit(1)`. A mistyped CIDR and an unreadable data directory produced
+ * the identical outcome — a process that is gone, and an operator whose only
+ * route back is the filesystem. Under a supervisor it is worse than useless: a
+ * process that exits on a bad config value restarts, fails identically, and
+ * restarts again, and nothing in that loop ever reaches the admin UI.
+ *
+ * __The test is not severity.__ A malformed deny rule is serious, and the
+ * instance should stop serving because of it. The question is whether stopping
+ * the *process* helps, and it only helps when the process cannot offer a way
+ * out.
+ *
+ * See D9 to D13 of docs/security-posture.md.
+ */
+/**
+ * Paths served in every state, so the maintenance page can render itself.
+ *
+ * Assets only. Adding a route here would open it during `starting` too, when
+ * the managers behind it are not up.
+ */
+export const STARTUP_BYPASS_PATHS = ['/css', '/js', '/images', '/themes', '/addons'];
+/** Exact paths served in every state. */
+const BYPASS_FILES = ['/favicon.ico', '/favicon.svg'];
+/**
+ * Paths served when the engine finished and a configuration value is unusable,
+ * but NOT while the engine is merely starting.
+ *
+ * The difference is whether the screens work. While the engine is initialising
+ * the managers behind `/admin` are not up, so letting a request through fails
+ * in a worse way than a 503. Once it has finished and only a value is wrong,
+ * they are exactly what the operator needs.
+ */
+const REPAIR_PATHS = ['/admin', '/login', '/logout'];
+/**
+ * Does `path` sit under `prefix` as a route, rather than merely starting with
+ * its characters?
+ *
+ * `/adminish` is an ordinary page and must not reach the admin bypass. Prefix
+ * matching without a boundary is how a gate springs a leak.
+ */
+function isUnder(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`) || path.startsWith(`${prefix}?`);
+}
+/**
+ * What the initialisation gate should do with a request.
+ *
+ * The server either is `engineReady` or it is not. What decides the third
+ * behaviour is not a third readiness value but a second, independent fact:
+ * whether the engine finished and a configuration value is unusable. Both are
+ * passed in, so the impossible combination — ready AND blocked — simply never
+ * arises at the call site rather than being modelled away.
+ */
+export function gateDecision(engineReady, blocked, path) {
+    if (engineReady)
+        return 'serve';
+    if (BYPASS_FILES.includes(path))
+        return 'serve';
+    if (STARTUP_BYPASS_PATHS.some((prefix) => isUnder(path, prefix)))
+        return 'serve';
+    // Blocked means the engine FINISHED and a value is wrong, so these screens
+    // work and are the only repair path without filesystem access. While merely
+    // starting they stay closed, because the managers behind them are not up.
+    if (blocked && REPAIR_PATHS.some((prefix) => isUnder(path, prefix)))
+        return 'serve';
+    return 'block';
+}
+/**
+ * The message shown on the maintenance page and logged at boot.
+ *
+ * Every reason at once, rather than the first: an operator who fixes one and
+ * restarts into the next has been made to do the work twice.
+ */
+export function describeBlocked(reasons) {
+    if (reasons.length === 0) {
+        // Blocked with no reason is an internal inconsistency: nothing sets the
+        // blocked state without recording why. Say "unknown" rather than render an
+        // empty page — and note that the repair path stays OPEN in this case, so
+        // an operator can still sign in and look, which is the recoverable answer.
+        return 'The instance is not serving because its configuration could not be used. '
+            + 'The reason is UNKNOWN, which is itself a bug — nothing should block the instance without recording why. '
+            + 'Please report it, and check the startup log.';
+    }
+    const list = reasons.map((r) => `• ${r}`).join('\n');
+    return `The instance is not serving because its configuration could not be used:\n${list}`;
+}
+/**
+ * What a visitor is told about a blocked instance: on the maintenance page and
+ * in `/health/readiness`, both served without sign-in (#1883).
+ *
+ * Every reason, as {@link describeBlocked} words them, unless one was recorded
+ * for administrators only (a site-critical add-on that did not load): then
+ * only `publicMessage`, and no reason at all — not even the ones that could be
+ * shown, since one detail beside a vague notice still says what failed.
+ * Administrators get the reasons in the log and the admin notification.
+ */
+export function blockedForVisitors(reasons, publicMessage) {
+    if (publicMessage !== null)
+        return { message: publicMessage, detail: [publicMessage] };
+    return { message: describeBlocked(reasons), detail: reasons };
+}
+/**
+ * #1883: what visitors see while a failure for administrators only holds the
+ * site in maintenance mode — a site-critical add-on that did not load, or an
+ * application database that cannot be opened safely (#1892). Empty leaves
+ * only the page's heading.
+ */
+export const SITE_CRITICAL_PUBLIC_MESSAGE_KEY = 'ngdpbase.managers.addons-manager.site-critical.public-message';
+/** The configured public message ({@link SITE_CRITICAL_PUBLIC_MESSAGE_KEY}); '' when unset or not a string. */
+export function sitePublicMessage(getProperty) {
+    const value = getProperty?.(SITE_CRITICAL_PUBLIC_MESSAGE_KEY, '');
+    return typeof value === 'string' ? value : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.19.0",
+  "version": "5.21.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",