@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/utils/auditEvents.js

@@ -0,0 +1,309 @@
+/**
+ * Audit event builders for content mutations (#1080).
+ *
+ * `AuditManager` was already mature — file provider with rotation, 90-day
+ * retention, search, stats, export, and an admin UI — but almost nothing
+ * called it. Outside the manager the only `logAuditEvent` call sites were
+ * `page-delete`, admin raw-edit, two session operations, and share
+ * issue/revoke. Ordinary page create, edit, and rename, and every attachment
+ * upload and delete, produced no audit record at all.
+ *
+ * That left "who changed this page, when, and through what?" answerable only
+ * from a version manifest: per-page, not queryable across pages, and present
+ * only when the deployment runs `versioningfileprovider` (the shipped default
+ * is `filesystemprovider`, which keeps no versions). There was no way to ask
+ * "everything this agent token wrote last Tuesday" — which is exactly the
+ * question agent tokens (#946) make worth asking, since a token writes
+ * unattended and the version manifest records only a username.
+ *
+ * These are pure builders so the event *shape* can be tested without an
+ * engine, a request, or a manager. The shape is the contract: `#1082` reads
+ * `page-rename`'s `fromPageName`/`pageName` pair to resolve a link that
+ * points at a page's former title, so those two fields are load-bearing
+ * rather than descriptive.
+ */
+import logger from './logger.js';
+import { auditEventDeclarations, AUDIT_EVENTS_KEY, isAuditEventEnabled, refusesOnFailure } from './auditRegistry.js';
+import { AUDIT_EVENT, isCoreAuditEventName } from './auditEventNames.js';
+import { proxyAttribution } from './proxyClaim.js';
+/**
+ * The result vocabulary, as a runtime value (#1237).
+ *
+ * The type alone could not be offered as filter options, so the audit page
+ * hand-kept its own list — and it offered `allow`, `deny`, `error` while the
+ * log holds `success` (5,859), `deny` (896) and `failure` (79). Two of the
+ * three options matched zero records and the largest value was unfilterable.
+ * Exactly the #1115 failure, one field over.
+ */
+export const AUDIT_RESULTS = ['success', 'failure', 'allow', 'deny', 'error', 'logout'];
+// #1201: the builders look the name up rather than interpolating it, so the
+// compiler — not a grep — knows which names each family can produce.
+const PAGE_EVENT = {
+    create: AUDIT_EVENT.PAGE_CREATE,
+    edit: AUDIT_EVENT.PAGE_EDIT,
+    rename: AUDIT_EVENT.PAGE_RENAME,
+    'link-rewrite': AUDIT_EVENT.PAGE_LINK_REWRITE
+};
+const ASSET_EVENT = {
+    upload: AUDIT_EVENT.ASSET_UPLOAD,
+    delete: AUDIT_EVENT.ASSET_DELETE
+};
+const TOKEN_EVENT = {
+    mint: AUDIT_EVENT.TOKEN_MINT,
+    revoke: AUDIT_EVENT.TOKEN_REVOKE,
+    extend: AUDIT_EVENT.TOKEN_EXTEND
+};
+/** A content row's "who" — `user`, `actor` and `ipAddress` — and the proxy grant's metadata. One place, read by every builder below. */
+function whoOf(input) {
+    const { metadata, ...proxy } = proxyAttribution(input.viaProxy);
+    return { fields: { user: input.username ?? 'unknown', ...proxy, ipAddress: input.ipAddress }, metadata };
+}
+/**
+ * Token identity as metadata. Always present as explicit nulls for a human
+ * write so a query can filter on the field existing rather than having to
+ * treat "absent" and "not a token" as the same thing.
+ */
+function tokenMetadata(viaToken) {
+    return {
+        viaTokenId: viaToken?.id ?? null,
+        viaTokenName: viaToken?.name ?? null
+    };
+}
+/**
+ * Build the audit event for a page create, edit, rename, or link rewrite.
+ *
+ * `result` is always `success`: these are recorded *after* the write lands,
+ * unlike `page-delete`, which logs `attempted` before unlinking so that a
+ * crash mid-delete still leaves a trace. A create or edit has the page file
+ * and its version history as its own record, so recording the attempt buys
+ * nothing the file does not already say.
+ */
+export function buildPageMutationAuditEvent(input) {
+    const { op, pageName, uuid, fromPageName, rewriteOf, viaToken } = input;
+    const who = whoOf(input);
+    const metadata = {
+        pageName,
+        uuid: uuid ?? null,
+        ...tokenMetadata(viaToken),
+        ...who.metadata
+    };
+    // Only a rename has a previous title. Emitting `fromPageName: null` on
+    // every edit would make the field useless as a filter for #1082.
+    if (op === 'rename' && fromPageName) {
+        metadata.fromPageName = fromPageName;
+    }
+    // Which rename this rewrite belongs to. Emitted only for `link-rewrite`, for
+    // the same reason: a field present on every event is useless as a filter.
+    if (op === 'link-rewrite' && rewriteOf) {
+        metadata.rewriteFrom = rewriteOf.from;
+        metadata.rewriteTo = rewriteOf.to;
+    }
+    return {
+        eventType: PAGE_EVENT[op],
+        ...who.fields,
+        action: `page-${op}`,
+        result: 'success',
+        // A token write is worth surfacing above ordinary editing traffic, but an
+        // edit is not a delete — `page-delete` reserves `high` for tokens.
+        severity: viaToken ? 'medium' : 'low',
+        metadata
+    };
+}
+/**
+ * Build the audit event for a page view (#1129).
+ *
+ * Emission is a deployment posture: `page-read` ships `enabled: false` in
+ * `ngdpbase.audit.events` (#1203), and `recordAuditEvent` honours the switch.
+ * Off, a general-purpose deployment does not drown its log in reads; on, a
+ * records-style deployment gets the access accounting — who looked at what —
+ * that read auditing exists for.
+ */
+export function buildPageViewAuditEvent(input) {
+    const { pageName, uuid, viaToken } = input;
+    const who = whoOf(input);
+    return {
+        eventType: AUDIT_EVENT.PAGE_READ,
+        ...who.fields,
+        action: 'page-read',
+        result: 'success',
+        // Same convention as the mutations: an unattended (token-driven) read is
+        // the one a reviewer is scanning for.
+        severity: viaToken ? 'medium' : 'low',
+        metadata: {
+            pageName,
+            uuid: uuid ?? null,
+            ...tokenMetadata(viaToken),
+            ...who.metadata
+        }
+    };
+}
+/**
+ * Build the audit event for an attachment upload or delete.
+ *
+ * A delete outranks an upload because it is the one that loses data, and a
+ * token-driven delete matches `page-delete`'s `high` for the same reason:
+ * unattended destruction is the case someone reviewing the log is looking for.
+ */
+export function buildAttachmentAuditEvent(input) {
+    const { op, attachmentId, filename, pageName, sizeBytes, viaToken } = input;
+    const who = whoOf(input);
+    const metadata = {
+        attachmentId,
+        filename,
+        ...tokenMetadata(viaToken),
+        ...who.metadata
+    };
+    if (pageName)
+        metadata.pageName = pageName;
+    if (typeof sizeBytes === 'number')
+        metadata.sizeBytes = sizeBytes;
+    const severity = op === 'delete'
+        ? (viaToken ? 'high' : 'medium')
+        : (viaToken ? 'medium' : 'low');
+    return {
+        eventType: ASSET_EVENT[op],
+        ...who.fields,
+        action: `asset-${op}`,
+        result: 'success',
+        severity,
+        metadata
+    };
+}
+const dropStats = { dropped: 0, lastEventType: null, lastError: null, lastAt: null };
+/** Audit writes lost since boot. Read-only snapshot. */
+export function getAuditDropStats() {
+    return { ...dropStats };
+}
+/** Reset the counter. For tests; nothing in the running app calls this. */
+export function resetAuditDropStats() {
+    dropStats.dropped = 0;
+    dropStats.lastEventType = null;
+    dropStats.lastError = null;
+    dropStats.lastAt = null;
+}
+/**
+ * Loud on the first loss, then at each power of ten.
+ *
+ * One line per dropped event would bury the signal in the noise of whatever
+ * outage caused it — and the first loss is the one that matters, because it is
+ * the moment the log stopped being complete.
+ */
+function shouldShout(count) {
+    if (count === 1)
+        return true;
+    let threshold = 10;
+    while (threshold <= count) {
+        if (threshold === count)
+            return true;
+        threshold *= 10;
+    }
+    return false;
+}
+export async function recordAuditEvent(sink, event, onError) {
+    // #1638: an addon's name is checked here, against the merged registry, not
+    // by the compiler. One nobody declares — the addon is disabled, or its
+    // config/default-config.json never named it — is refused loudly rather than
+    // recorded under a name with no on-failure rule. Core names are the
+    // generated union and keep their existing path.
+    if (!isCoreAuditEventName(event.eventType) && !auditEventDeclarations()[event.eventType]) {
+        const message = `Audit event '${event.eventType}' is not declared (as a permission entry's audit block, or in ${AUDIT_EVENTS_KEY}). ` +
+            'An addon declares its events in its config/default-config.json, and they count only while the addon is enabled.';
+        logger.error(`[audit] ${message}`);
+        throw new Error(message);
+    }
+    // #1203: `enabled: false` on the event in `ngdpbase.audit.events` is a
+    // decision on the record. The emitter still exists and still calls this;
+    // the switch is honoured here, once, rather than at every call site.
+    if (!isAuditEventEnabled(event.eventType))
+        return 'not-enabled';
+    // An absent sink is a configuration state, not a failure. Counting it would
+    // make the number meaningless on any instance that never enabled auditing —
+    // and it must not turn every critical action into an error either, since
+    // auditing being off is already visible through #1118's posture.
+    if (!sink?.logAuditEvent)
+        return 'no-sink';
+    const critical = refusesOnFailure(event.eventType);
+    if (critical && !sink.flushAuditQueue) {
+        const message = `Audit sink cannot guarantee durability for ${event.eventType}, which is declared on-failure: refuse. ` +
+            'The action was refused rather than completed without a record.';
+        logger.error(`[audit] ${message}`);
+        throw new Error(message);
+    }
+    try {
+        await sink.logAuditEvent(event);
+        if (critical)
+            await sink.flushAuditQueue?.();
+        return 'recorded';
+    }
+    catch (err) {
+        dropStats.dropped += 1;
+        dropStats.lastEventType = event.eventType;
+        dropStats.lastError = err instanceof Error ? err.message : String(err);
+        dropStats.lastAt = new Date().toISOString();
+        if (shouldShout(dropStats.dropped)) {
+            logger.error(`[audit] ${dropStats.dropped} audit event(s) lost since boot — latest ${event.eventType}: ${dropStats.lastError}. ` +
+                'The write itself succeeded; only its audit record was lost.');
+        }
+        onError?.(err);
+        // A critical event's failure is the caller's problem: it must be able to
+        // abandon the action rather than complete it unrecorded.
+        if (critical) {
+            throw new Error(`Audit write failed for ${event.eventType}, which is declared on-failure: refuse: ${dropStats.lastError}`, { cause: err });
+        }
+        return 'dropped';
+    }
+}
+/**
+ * Build the audit event for an agent token mint, extend or revoke (#1111, #1734).
+ *
+ * Before this, the token store was the only record that a credential had ever
+ * existed — and `purgeExpired()` claimed otherwise in a comment ("Audit is
+ * unaffected") while nothing emitted anything. That made `retention-days`
+ * load-bearing by accident: hash-bearing records were kept a month past
+ * usefulness purely so somebody could answer "what could this token do, and
+ * who stopped it?" With the lifecycle audited, the store can keep only what it
+ * needs to authenticate.
+ *
+ * Emitted from the manager rather than the route, unlike `page.*`. A page
+ * mutation logged at the HTTP layer misses an internal caller and that is
+ * survivable; an unaudited mint is a credential nobody knows exists.
+ *
+ * `scopes` appear on a mint only, `expiresAt` on a mint and an extend (with
+ * `previousExpiresAt` on an extend, #1734), and `revokedBy` on a revoke only —
+ * the same rule `page-rename` follows for `fromPageName`. A field present on
+ * every event is useless as a filter.
+ */
+export function buildTokenAuditEvent(input) {
+    const { op, id, owner, name, scopes, expiresAt, previousExpiresAt, revokedBy, viaToken } = input;
+    const who = whoOf(input);
+    const metadata = {
+        id,
+        owner,
+        name: name ?? null,
+        ...tokenMetadata(viaToken),
+        ...who.metadata
+    };
+    if (op === 'mint') {
+        metadata.scopes = [...(scopes ?? [])];
+        metadata.expiresAt = expiresAt;
+    }
+    if (op === 'extend') {
+        metadata.previousExpiresAt = previousExpiresAt;
+        metadata.expiresAt = expiresAt;
+    }
+    if (op === 'revoke' && revokedBy) {
+        metadata.revokedBy = revokedBy;
+    }
+    return {
+        eventType: TOKEN_EVENT[op],
+        ...who.fields,
+        action: `token-${op}`,
+        result: 'success',
+        // Every credential event outranks ordinary content traffic: a token acts
+        // unattended, so its creation and its revocation are what a reader of the
+        // log is looking for. A token minted BY a token is higher still — that is
+        // delegation widening on its own, and the case worth surfacing loudest.
+        severity: viaToken ? 'high' : 'medium',
+        metadata
+    };
+}

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

@@ -0,0 +1,102 @@
+/**
+ * The audit event registry, read from configuration (#1200, epic #1208).
+ *
+ * `ngdpbase.audit.events` in `config/app-default-config.json` names every
+ * recorded action, what happens when its record cannot be written, and whether it fires. This module is
+ * a reader over that map: nothing here declares an event.
+ *
+ * Until #1200 the declarations lived in this file, deliberately, on the
+ * argument that an operator who could edit them could narrow what the system
+ * claims to audit. The operator's decision on 2026-09-04 is that this is the
+ * point: configuration is authoritative, and narrowing is on the record —
+ * an admin UI edit emits `config-change`, and a disk edit is reported by
+ * `posture-recorded` at the next boot. See docs/audit-posture.md.
+ *
+ * #1638 (operator, 2026-10-05): a permission and its action are one thing. An
+ * event that records a permission's action is declared on the permission
+ * entry itself — `ngdpbase.permissions.definitions.<name>.audit` — and
+ * `ngdpbase.audit.events` holds only events that are not a permission's
+ * action. {@link auditDeclarationsFrom} reads both, and is the one reader:
+ * the runtime, the generator, the lint, the doc generator and the boot check
+ * all call it, so they cannot disagree.
+ *
+ * What stays in code is the emitters. `scripts/audit-coverage.ts` proves the
+ * map and the emitters agree.
+ */
+export declare const AUDIT_EVENTS_KEY = "ngdpbase.audit.events";
+/** The permission registry; an entry's `audit` field declares its event (#1638). */
+export declare const PERMISSION_DEFINITIONS_KEY = "ngdpbase.permissions.definitions";
+/**
+ * What happens when the record cannot be written (#1121, #1158, #1218).
+ *
+ * - `refuse`   — the action must not complete unless the record does; the
+ *                write is flushed to the device before the action proceeds
+ * - `continue` — the action proceeds; the lost record is counted and surfaced
+ *
+ * This is failure handling, not importance. How important an event is lives
+ * on each record as `severity`. Until #1218 this field was called `tier` with
+ * values `critical` / `standard` / `volume`, which read as an importance
+ * scale that it never was; `volume` was `continue` plus `enabled: false`.
+ */
+export type AuditOnFailure = 'refuse' | 'continue';
+/** One entry of `ngdpbase.audit.events`. */
+export interface AuditEventDeclaration {
+    'on-failure': AuditOnFailure;
+    /** Whether the emitter fires. Omitted means true; `false` is a decision on the record. */
+    enabled?: boolean;
+    /** One line, shown in the admin filter and the documented table. */
+    description: string;
+}
+/** The shape of `ConfigurationManager.getProperty`, so this module needs no manager import. */
+export type AuditEventsSource = (key: string, defaultValue?: unknown) => unknown;
+/**
+ * Bind the live configuration. `AuditManager.initialize` calls this before it
+ * loads a provider, so every tier consulted from then on is the operator's.
+ *
+ * There is no fallback to the shipped file: reading
+ * `config/app-default-config.json` here would be a second reader over the
+ * configuration store, and a value could then come from the file when the live
+ * configuration says otherwise. Tests bind from the shipped file themselves
+ * (`vitest.setup.ts`), which is the one honest direct read.
+ */
+export declare function bindAuditEvents(source: AuditEventsSource | null): void;
+/**
+ * Every declared event in a configuration (#1638): the entries of
+ * `ngdpbase.audit.events`, plus every permission entry carrying `audit`, under
+ * the permission's name. A permission's `audit.description` defaults to the
+ * permission's own description.
+ *
+ * A name in both places is a declaration made twice. The shipped file never
+ * does it (`npm run lint:audit` fails); an operator's custom file that still
+ * sets a moved event under `ngdpbase.audit.events` is honoured — its fields
+ * override the permission's — and said once, so it is never silent.
+ */
+export declare function auditDeclarationsFrom(read: AuditEventsSource): Record<string, AuditEventDeclaration>;
+/** Every declared event, from the bound configuration. Empty, and said once, before binding. */
+export declare function auditEventDeclarations(): Record<string, AuditEventDeclaration>;
+/** The declaration for one event, or null when configuration does not name it. */
+export declare function auditEventDeclaration(eventType: string): AuditEventDeclaration | null;
+/** Every declared event type, sorted. */
+export declare function auditEventTypes(): string[];
+/** Every event type this system undertakes to emit: declared and not switched off. */
+export declare function requiredEventTypes(): string[];
+/** Is this event switched on? An undeclared event is not switched off. */
+export declare function isAuditEventEnabled(eventType: string): boolean;
+/**
+ * Does this event refuse the action when its record cannot be written
+ * (#1121, #1158)?
+ *
+ * Two layers need the same answer and must not be able to disagree:
+ * `recordAuditEvent` decides whether a failure rejects the action, and
+ * `FileAuditProvider.writeEvent` decides whether the record is fsynced before
+ * the write resolves. A rule that meant one thing to the caller and another to
+ * the writer would be the #1148 defect again.
+ */
+export declare function refusesOnFailure(eventType: string): boolean;
+/** Every event type that refuses on failure, for reporting what the rule covers. */
+export declare function refuseOnFailureEventTypes(): string[];
+/** Events declared and switched off, with the reason. The honest half of the answer. */
+export declare function disabledEventTypes(): Array<{
+    eventType: string;
+    description: string;
+}>;

package/lib/src/utils/auditRegistry.js

@@ -0,0 +1,168 @@
+/**
+ * The audit event registry, read from configuration (#1200, epic #1208).
+ *
+ * `ngdpbase.audit.events` in `config/app-default-config.json` names every
+ * recorded action, what happens when its record cannot be written, and whether it fires. This module is
+ * a reader over that map: nothing here declares an event.
+ *
+ * Until #1200 the declarations lived in this file, deliberately, on the
+ * argument that an operator who could edit them could narrow what the system
+ * claims to audit. The operator's decision on 2026-09-04 is that this is the
+ * point: configuration is authoritative, and narrowing is on the record —
+ * an admin UI edit emits `config-change`, and a disk edit is reported by
+ * `posture-recorded` at the next boot. See docs/audit-posture.md.
+ *
+ * #1638 (operator, 2026-10-05): a permission and its action are one thing. An
+ * event that records a permission's action is declared on the permission
+ * entry itself — `ngdpbase.permissions.definitions.<name>.audit` — and
+ * `ngdpbase.audit.events` holds only events that are not a permission's
+ * action. {@link auditDeclarationsFrom} reads both, and is the one reader:
+ * the runtime, the generator, the lint, the doc generator and the boot check
+ * all call it, so they cannot disagree.
+ *
+ * What stays in code is the emitters. `scripts/audit-coverage.ts` proves the
+ * map and the emitters agree.
+ */
+import logger from './logger.js';
+export const AUDIT_EVENTS_KEY = 'ngdpbase.audit.events';
+/** The permission registry; an entry's `audit` field declares its event (#1638). */
+export const PERMISSION_DEFINITIONS_KEY = 'ngdpbase.permissions.definitions';
+let boundSource = null;
+let warnedUnbound = false;
+const warnedUndeclared = new Set();
+/**
+ * Bind the live configuration. `AuditManager.initialize` calls this before it
+ * loads a provider, so every tier consulted from then on is the operator's.
+ *
+ * There is no fallback to the shipped file: reading
+ * `config/app-default-config.json` here would be a second reader over the
+ * configuration store, and a value could then come from the file when the live
+ * configuration says otherwise. Tests bind from the shipped file themselves
+ * (`vitest.setup.ts`), which is the one honest direct read.
+ */
+export function bindAuditEvents(source) {
+    boundSource = source;
+    warnedUnbound = false;
+}
+function asDeclarations(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [name, entry] of Object.entries(value)) {
+        // A custom config removes a shipped entry by setting it to null.
+        if (!entry || typeof entry !== 'object')
+            continue;
+        out[name] = entry;
+    }
+    return out;
+}
+const warnedDoubled = new Set();
+/**
+ * Every declared event in a configuration (#1638): the entries of
+ * `ngdpbase.audit.events`, plus every permission entry carrying `audit`, under
+ * the permission's name. A permission's `audit.description` defaults to the
+ * permission's own description.
+ *
+ * A name in both places is a declaration made twice. The shipped file never
+ * does it (`npm run lint:audit` fails); an operator's custom file that still
+ * sets a moved event under `ngdpbase.audit.events` is honoured — its fields
+ * override the permission's — and said once, so it is never silent.
+ */
+export function auditDeclarationsFrom(read) {
+    const events = asDeclarations(read(AUDIT_EVENTS_KEY, {}));
+    const permissions = read(PERMISSION_DEFINITIONS_KEY, {});
+    const out = {};
+    if (permissions && typeof permissions === 'object' && !Array.isArray(permissions)) {
+        for (const [name, entry] of Object.entries(permissions)) {
+            const audit = entry?.audit;
+            if (!audit || typeof audit !== 'object')
+                continue;
+            const description = entry.description;
+            out[name] = { description: typeof description === 'string' ? description : name, ...audit };
+        }
+    }
+    // A custom file written before #1638 removed an event with null in the
+    // events map; that still removes it, wherever it is now declared.
+    const rawEvents = read(AUDIT_EVENTS_KEY, {});
+    if (rawEvents && typeof rawEvents === 'object' && !Array.isArray(rawEvents)) {
+        for (const [name, entry] of Object.entries(rawEvents)) {
+            if (entry === null)
+                delete out[name];
+        }
+    }
+    for (const [name, d] of Object.entries(events)) {
+        if (out[name] && !warnedDoubled.has(name)) {
+            warnedDoubled.add(name);
+            logger.warn(`[audit] '${name}' is declared in ${AUDIT_EVENTS_KEY} and on its permission entry; the ${AUDIT_EVENTS_KEY} entry wins. Move it to ${PERMISSION_DEFINITIONS_KEY}.${name}.audit (#1638).`);
+        }
+        out[name] = { ...out[name], ...d };
+    }
+    return out;
+}
+/** Every declared event, from the bound configuration. Empty, and said once, before binding. */
+export function auditEventDeclarations() {
+    if (!boundSource) {
+        if (!warnedUnbound) {
+            warnedUnbound = true;
+            logger.warn(`[audit] ${AUDIT_EVENTS_KEY} is not bound yet; every event is treated as on-failure: continue until AuditManager initialises`);
+        }
+        return {};
+    }
+    return auditDeclarationsFrom(boundSource);
+}
+/** The declaration for one event, or null when configuration does not name it. */
+export function auditEventDeclaration(eventType) {
+    const d = auditEventDeclarations()[eventType];
+    if (d)
+        return d;
+    // Never silent: an emitter producing a name configuration does not declare
+    // is treated as `standard` and said once, so the gap is visible in the log
+    // rather than in an assessor's report.
+    if (eventType && !warnedUndeclared.has(eventType)) {
+        warnedUndeclared.add(eventType);
+        logger.warn(`[audit] '${eventType}' is emitted but not declared in ${AUDIT_EVENTS_KEY}; treated as on-failure: continue`);
+    }
+    return null;
+}
+/** Every declared event type, sorted. */
+export function auditEventTypes() {
+    return Object.keys(auditEventDeclarations()).sort();
+}
+/** Every event type this system undertakes to emit: declared and not switched off. */
+export function requiredEventTypes() {
+    return Object.entries(auditEventDeclarations())
+        .filter(([, d]) => d.enabled !== false)
+        .map(([name]) => name)
+        .sort();
+}
+/** Is this event switched on? An undeclared event is not switched off. */
+export function isAuditEventEnabled(eventType) {
+    return auditEventDeclaration(eventType)?.enabled !== false;
+}
+/**
+ * Does this event refuse the action when its record cannot be written
+ * (#1121, #1158)?
+ *
+ * Two layers need the same answer and must not be able to disagree:
+ * `recordAuditEvent` decides whether a failure rejects the action, and
+ * `FileAuditProvider.writeEvent` decides whether the record is fsynced before
+ * the write resolves. A rule that meant one thing to the caller and another to
+ * the writer would be the #1148 defect again.
+ */
+export function refusesOnFailure(eventType) {
+    return auditEventDeclaration(eventType)?.['on-failure'] === 'refuse';
+}
+/** Every event type that refuses on failure, for reporting what the rule covers. */
+export function refuseOnFailureEventTypes() {
+    return Object.entries(auditEventDeclarations())
+        .filter(([, d]) => d['on-failure'] === 'refuse' && d.enabled !== false)
+        .map(([name]) => name)
+        .sort();
+}
+/** Events declared and switched off, with the reason. The honest half of the answer. */
+export function disabledEventTypes() {
+    return Object.entries(auditEventDeclarations())
+        .filter(([, d]) => d.enabled === false)
+        .map(([eventType, d]) => ({ eventType, description: d.description }))
+        .sort((a, b) => a.eventType.localeCompare(b.eventType));
+}

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

@@ -0,0 +1,2 @@
+/** BIP-0039 English wordlist (official 2048 words). */
+export declare const BIP39_ENGLISH: readonly string[];

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

@@ -0,0 +1,68 @@
+/**
+ * Environment-owned configuration keys (#1089).
+ *
+ * Six keys used to be owned by two layers at once: the environment, via a
+ * hardcoded map inside `ConfigurationManager.getProperty()` that nothing
+ * outside could see, and the admin configuration screen, which accepted and
+ * persisted edits to them that could never take effect — the override was
+ * checked *before* the merged config, so the write was inert immediately, not
+ * merely on next boot.
+ *
+ * The rule this restores: **a configuration key is owned by exactly one layer,
+ * never both.** Ownership is now declared in `ngdpbase.config.env-keys`,
+ * mirroring the `ngdpbase.config.sensitive-values` (its `secret` entries) precedent — a map rather than an
+ * array, because the UI needs the variable's name to tell an operator where the
+ * value actually lives.
+ *
+ * Two decisions worth keeping straight, both settled deliberately:
+ *
+ * - **Ownership is not conditional on the variable being set.** A key in the
+ *   map is env-owned whether or not anything is currently exporting it. Making
+ *   it conditional would hand the UI the source of truth whenever the variable
+ *   is absent, which is precisely the ambiguity being removed.
+ * - **The shipped value is a boot fallback, not a setting.** It exists so a
+ *   fresh install comes up. `describePropertySource` still reports it as the
+ *   *effective* value when nothing overrides it, because the screen must show
+ *   what is actually in force — but the field stays read-only either way.
+ */
+/** Config key holding the declared map of env-owned keys. */
+export declare const ENV_KEYS_CONFIG_KEY = "ngdpbase.config.env-keys";
+/** key → environment variable that supplies it. */
+export type EnvKeyMap = Record<string, string>;
+export interface PropertyDescription {
+    /** Whether this key is declared env-owned. Independent of whether the variable is set. */
+    envControlled: boolean;
+    /** The variable that owns it, or null when not env-owned. */
+    envVar: string | null;
+    /** The value actually in force right now. */
+    effective: unknown;
+    /** Where `effective` came from. */
+    source: 'env' | 'config';
+}
+/**
+ * Coerce an environment value to the type of the shipped default.
+ *
+ * Environment values are always strings, but the rest of the code expects the
+ * declared type — `ngdpbase.server.port` is `number` in `src/types/Config.ts`
+ * and ships as `3000`, so `NGDPBASE_PORT=3001` must not arrive as `"3001"` and
+ * quietly fail an arithmetic comparison somewhere downstream.
+ *
+ * Using the default's own type rather than a per-key table means there is one
+ * rule and nothing to keep in sync as keys are added.
+ *
+ * When the value cannot be coerced — a non-numeric string against a numeric
+ * default — the raw string is returned. Handing the caller something visibly
+ * wrong beats handing them a silent `NaN`.
+ */
+export declare function coerceToTypeOf(value: string, defaultValue: unknown): unknown;
+/**
+ * Describe where a config key's value comes from.
+ *
+ * @param key - The config key.
+ * @param envKeys - The declared map, or null when unavailable.
+ * @param env - Environment to read, normally `process.env`. Injected so this
+ *   stays pure and testable.
+ * @param configValue - The merged config value, used both as the fallback and
+ *   as the type to coerce an environment value to.
+ */
+export declare function describePropertySource(key: string, envKeys: EnvKeyMap | null | undefined, env: Record<string, string | undefined>, configValue: unknown): PropertyDescription;