@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,175 @@
+/**
+ * Process-level unlock bag for private-store keys (#1384, #1391).
+ *
+ * Keyed by an opaque random handle — never the session id — created at
+ * password login ({@link newPrivateStoreHandle}), stored on the session as
+ * `privateStoreHandle`, and carried on the request subject so a caller reaches
+ * its keys through the context it was given ({@link dekFor}; security-posture
+ * P1). Key bytes never go into express-session JSON, a context, or a record.
+ * Logout calls {@link lockPrivateStores}.
+ *
+ * There is no ambient slot: `AsyncLocalStorage` is refused by P1 because the
+ * call site does not show what identity it runs under. Every caller reaches
+ * its keys through the context it was handed.
+ */
+import { type PrivateStoreLayout } from './privateStorePath.js';
+import { type UserCatalog } from './privateStoreCatalogs.js';
+import type { ActorContext } from '../context/ActorContext.js';
+import type { LinkPublicKey, Lockbox } from './shareLockbox.js';
+export declare function unlockPrivateStores(sessionId: string, username: string, kek: Buffer): void;
+export declare function getSessionUserIndex(sessionId: string): UserCatalog | undefined;
+export declare function lockPrivateStores(sessionId: string): void;
+export declare function getUnlockedKek(sessionId: string): Buffer | undefined;
+export declare function setUnlockedDek(sessionId: string, storeId: string, dek: Buffer): void;
+export declare function getUnlockedDek(sessionId: string, storeId: string): Buffer | undefined;
+/** DEK from the process bag for this request's session (or an explicit id). */
+export declare function sessionDekForStore(storeId: string, handle: string): Buffer | undefined;
+/**
+ * After password login: unwrap the user KEK into the bag and load store DEKs.
+ * No-ops when the user has no envelope yet. Never writes key bytes to session JSON.
+ */
+export declare function unlockPrivateStoresWithPassword(args: {
+    /** The session's private-store handle ({@link newPrivateStoreHandle}), not its session id. */
+    handle: string;
+    username: string;
+    password: string;
+    pagesDirectory: string;
+}): Promise<void>;
+/**
+ * Unlock with the 12 recovery words instead of the password (#1453).
+ *
+ * The words unwrap the SAME key the password does — the envelope holds it
+ * twice, once per wrap — so everything after the unwrap is the password
+ * path's, shared. Wrong words fail the authenticated unwrap and return
+ * `false`; nothing is unlocked and nothing is written. The words are never
+ * logged, stored or returned.
+ */
+export declare function unlockPrivateStoresWithMnemonic(args: {
+    handle: string;
+    username: string;
+    words: string;
+    pagesDirectory: string;
+}): Promise<boolean>;
+/** Whether `username` has keys at all, i.e. a store that can be encrypted. */
+export declare function hasUserKeys(pagesDirectory: string, username: string): Promise<boolean>;
+/**
+ * The public half of `username`'s key pair (#1762 slice 5), or null when they
+ * have no keys or no pair yet. Public: anyone may seal to it.
+ */
+export declare function personKeyOf(pagesDirectory: string, username: string): Promise<LinkPublicKey | null>;
+/**
+ * Seal a copy of this context's OWN unlocked KEK to `recipient` (#1762 slice
+ * 5): what a proxy grant made while the owner's store is open carries. Null
+ * when the context holds no key — a locked store, a token, a proxy (it holds
+ * no KEK of its own through `kekFor`). The KEK copy taken here is zeroed.
+ */
+export declare function sealKekCopyFor(ctx: ActorContext, recipient: LinkPublicKey): Promise<Lockbox | null>;
+/**
+ * Open the key copy a proxy grant carries (#1762 slice 5) into the actor's
+ * own bag (`handle`), when the actor's store is unlocked: their KEK unwraps
+ * their private key, which opens the copy of the owner's KEK, which opens the
+ * owner's encrypted stores. Replaces any copy the bag held. False — nothing
+ * held — when the actor's store is locked, the bag is not the actor's, or the
+ * copy does not open (it is then not retried for this bag). No key byte is
+ * returned or logged.
+ */
+export declare function openKeyCopy(args: {
+    handle: string;
+    actor: string;
+    grantId: string;
+    owner: string;
+    copy: Lockbox;
+    pagesDirectory: string;
+}): Promise<boolean>;
+/** The grant and person whose key copy this handle's bag holds, if any — ids only, no key. */
+export declare function heldKeyCopy(handle: unknown): {
+    grantId: string;
+    owner: string;
+} | undefined;
+/** Wipe the key copy this handle's bag holds (#1762 slice 5): switching back, or to someone else. The actor's own keys stay. */
+export declare function dropKeyCopy(handle: unknown): void;
+/** Wipe every copy opened under this grant, in every session (#1762 slice 5): the grant was revoked or its account closed. */
+export declare function dropKeyCopiesOfGrant(grantId: string): number;
+/**
+ * Password change: re-wrap the user envelope. Recovery wrap is unchanged.
+ * No-ops when there is no envelope yet. Not a manager — any caller can use this.
+ */
+export declare function rewrapUserKeysOnPasswordChange(args: {
+    pagesDirectory: string;
+    username: string;
+    oldPassword: string;
+    newPassword: string;
+}): Promise<void>;
+/**
+ * A forgotten password, reset with the recovery words (#1452): the words
+ * unwrap the KEK, and the password wrap is replaced with one made from the
+ * new password. The recovery wrap and the KEK are untouched.
+ *
+ * Returns `false` — writing nothing — when the user has no keys or the words
+ * do not open them. The words are never logged or stored.
+ */
+export declare function resetPasswordWrapWithMnemonic(args: {
+    pagesDirectory: string;
+    username: string;
+    words: string;
+    newPassword: string;
+}): Promise<boolean>;
+/** A fresh handle for a session's key bag: random, never the session id. */
+export declare function newPrivateStoreHandle(): string;
+/**
+ * The DEK for `owner`'s `store` that this context holds, if any. Only from the
+ * owner's own bag — DEKs are keyed by store id, and every user has a
+ * `default` — or, for someone acting for the owner, from the key copy their
+ * grant carries (#1762 slice 5).
+ */
+export declare function dekFor(ctx: ActorContext | undefined, owner: string, store: string): Buffer | undefined;
+/**
+ * The ids of the requester's OWN stores whose DEK its session holds (#1400) —
+ * the encrypted stores it can open right now. Another user's, or a locked
+ * store, is never listed; acting for someone, the represented person's stores
+ * the grant's key copy opened (#1762 slice 5). Ids only: no key bytes leave
+ * the bag.
+ */
+export declare function unlockedStoreIdsFor(ctx: ActorContext): string[];
+/** The unlocked sealed-store page catalog this context's session holds, if any (#1385). */
+export declare function userIndexFor(ctx: ActorContext | undefined): UserCatalog | undefined;
+/**
+ * Refuse a write into an encrypted store unless this context holds its DEK
+ * (#1394). The context-carrying form of {@link assertCurrentSessionCanWriteStore}.
+ */
+export declare function assertContextCanWriteStore(ctx: ActorContext, args: {
+    pagesDirectory: string;
+    owner: string;
+    store: string;
+    layout: PrivateStoreLayout;
+}): Promise<void>;
+/**
+ * Whether this context's session holds an unlocked user key (#1448).
+ *
+ * A yes/no, deliberately. {@link kekFor} hands back a COPY of the key bytes,
+ * which is right for a caller that is about to use them and wrong for one that
+ * only needs to know they exist — every page render asks this, and none of
+ * them should be copying key material into a buffer it then has to remember
+ * to zero.
+ */
+export declare function hasUnlockedKey(ctx: ActorContext | undefined): boolean;
+/** The user KEK this context's session holds, if any. */
+export declare function kekFor(ctx: ActorContext | undefined): Buffer | undefined;
+/**
+ * The one door for a session ending (#1626): whatever ends it — logout, idle
+ * timeout, a password change, an admin revoke, a new sign-in on the same
+ * browser — calls this with the session's private-store handle before the
+ * session is gone, so its keys are zeroed and dropped and no recovery words
+ * stay pending. Takes the raw session value, so a caller never re-implements
+ * the "is there a handle" check.
+ */
+export declare function endSessionKeys(handle: unknown): void;
+/**
+ * Drop every unlocked bag whose handle no live session holds (#1626): a
+ * session that expired in the store, or one destroyed by a path that could
+ * not reach endSessionKeys, leaves its keys with no owner. Returns how many
+ * bags were dropped.
+ */
+export declare function sweepOrphanedKeys(liveHandles: ReadonlySet<string>): number;
+/** Test teardown only. */
+export declare function clearUnlockedPrivateStores(): void;

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

@@ -0,0 +1,59 @@
+/**
+ * The rules about a subject's `viaProxy` that more than one door reads
+ * (#1762 slice 2), declared once.
+ *
+ * The decision itself — the grant still in force, the action in it, the actor
+ * holding it — is `PolicyDecisionPoint.ceiling`'s. What lives here is what a
+ * door with no decision point to hand needs: the private-container rule
+ * (`mayActInPrivateContainer`) and the "does this subject carry a ceiling at
+ * all" question the page door and the list filter ask before calling it.
+ */
+import type { AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
+import type { ShareGrant } from '../types/Share.js';
+/** The delegations a subject may carry, as the rules below read them. */
+interface Delegations {
+    viaToken?: AgentTokenGrant;
+    viaShare?: ShareGrant;
+    viaProxy?: ProxyClaim;
+}
+/**
+ * Does this proxy claim carry `permission`? Only a `kind: 'proxy'` claim
+ * carries anything: `impersonation` is reserved for #1763 and admits nothing.
+ *
+ * Read for a permission the grant carries as a marker rather than one policy
+ * is asked: `vault-proxy`, which lets the proxy into the represented person's
+ * private container (`mayActInPrivateContainer`). Without it a proxy acts on
+ * everything else the grant allows and never reaches a vault; an encrypted vault
+ * opens only through the key copy the owner sealed to the proxy (slice 5).
+ */
+export declare function proxyCarries(claim: ProxyClaim | undefined, permission: string): boolean;
+/**
+ * A subject acting for someone AND carrying an agent token or a share link.
+ * Never built legitimately (an agent-token request can never act for anyone),
+ * so every door refuses it rather than deciding which ceiling wins.
+ */
+export declare function mixesProxyWithDelegation(subject: Delegations | null | undefined): boolean;
+/** Does the subject carry any delegation the PDP's ceiling bounds — a token, a share, or a proxy claim? */
+export declare function carriesCeiling(subject: Delegations | null | undefined): boolean;
+/**
+ * What a proxy claim adds to an audit record (#1762 slice 3), declared once.
+ *
+ * Operator decision: a row for something done under a proxy grant names the
+ * represented person in `user` — the account acted on, as with agent tokens —
+ * and the person who actually did it in a separate top-level `actor`, which
+ * the audit search filters on. The grant's id goes in the metadata so the row
+ * joins to the `proxy-grant` record that allowed it. A row with no proxy claim
+ * gets neither: `actor` is absent, never a copy of `user`.
+ *
+ * Every builder of an audit row's "who" reads this — `actorOf` for a request
+ * subject, `attributedTo` for a job, `PolicyInformationPoint.auditDenial` for a
+ * subject that may be anonymous, and the content builders in `auditEvents.ts`.
+ */
+export interface ProxyAttribution {
+    /** The person who acted; present only under a proxy claim. */
+    actor?: string;
+    /** `delegated` (the claim's kind) and `proxyGrantId`; empty without a claim. */
+    metadata: Record<string, unknown>;
+}
+export declare function proxyAttribution(claim: ProxyClaim | null | undefined): ProxyAttribution;
+export {};

package/lib/src/utils/proxyClaim.js

@@ -0,0 +1,30 @@
+/**
+ * Does this proxy claim carry `permission`? Only a `kind: 'proxy'` claim
+ * carries anything: `impersonation` is reserved for #1763 and admits nothing.
+ *
+ * Read for a permission the grant carries as a marker rather than one policy
+ * is asked: `vault-proxy`, which lets the proxy into the represented person's
+ * private container (`mayActInPrivateContainer`). Without it a proxy acts on
+ * everything else the grant allows and never reaches a vault; an encrypted vault
+ * opens only through the key copy the owner sealed to the proxy (slice 5).
+ */
+export function proxyCarries(claim, permission) {
+    return claim?.kind === 'proxy' && Array.isArray(claim.scopes) && claim.scopes.includes(permission);
+}
+/**
+ * A subject acting for someone AND carrying an agent token or a share link.
+ * Never built legitimately (an agent-token request can never act for anyone),
+ * so every door refuses it rather than deciding which ceiling wins.
+ */
+export function mixesProxyWithDelegation(subject) {
+    return Boolean(subject?.viaProxy && (subject.viaToken || subject.viaShare));
+}
+/** Does the subject carry any delegation the PDP's ceiling bounds — a token, a share, or a proxy claim? */
+export function carriesCeiling(subject) {
+    return Boolean(subject?.viaToken || subject?.viaShare || subject?.viaProxy);
+}
+export function proxyAttribution(claim) {
+    if (!claim)
+        return { metadata: {} };
+    return { actor: claim.actor, metadata: { delegated: claim.kind, proxyGrantId: claim.grantId } };
+}

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

@@ -0,0 +1,21 @@
+import type { Logform } from 'winston';
+/** What a struck title is replaced with. */
+export declare const REDACTED_TITLE = "[redacted]";
+/**
+ * Strike the title from every private page name in `text`.
+ *
+ * @param text - a log line, message or audit field
+ * @returns the text with each private title replaced by `[redacted]`
+ */
+export declare function redactPrivateNames(text: string): string;
+/**
+ * The same, over every string in a value — an audit event's fields,
+ * metadata and context. Other values are returned as they are.
+ */
+export declare function redactPrivateNamesDeep<T>(value: T): T;
+/**
+ * Winston format striking private titles from the message, any stack, and
+ * the metadata a line carries (`logger.info(msg, { pageName })`). Placed
+ * before `printf`, beside redactSecretsFormat, so every transport gets it.
+ */
+export declare function redactPrivateNamesFormat(): Logform.Format;

package/lib/src/utils/redactPrivateNames.js

@@ -0,0 +1,89 @@
+/**
+ * redactPrivateNames — keep private page titles out of logs and the audit
+ * trail (#1461, epic #1454).
+ *
+ * A private page is named by its path, `vaults/{owner}/{store}/{title}`
+ * (#1456; `private/…` before #1506, still matched). Its title belongs to its owner's store; nobody else — admin
+ * included — may read it, and `/admin/logs` and the audit view are read by
+ * admins. So wherever such a name reaches a log line or an audit event, the
+ * title is struck and the owner and store are kept: the line stays
+ * diagnosable ("a page in molly's default store") without saying which page.
+ *
+ * Three shapes are recognised, because a name reaches a line in all three:
+ *
+ *   - as written:     `vaults/molly/default/Merger notes`
+ *   - in a URL path:  `/vaults/molly/default/Merger%20notes/edit`
+ *   - URL-encoded:    `vaults%2Fmolly%2Fdefault%2FMerger%20notes`
+ *
+ * A bare title — `Loaded MergerNotes from …` — cannot be told from any other
+ * word, so the code that knows a page is private logs its uuid instead. This
+ * catches every line that names the page the way the rest of the system does.
+ *
+ * Like redactSecrets, this module never imports the logger (bootstrap cycle).
+ */
+import { format } from 'winston';
+import { LEGACY_PRIVATE_ROOT, PRIVATE_URL_SEGMENT } from './privateStorePath.js';
+/** What a struck title is replaced with. */
+export const REDACTED_TITLE = '[redacted]';
+/** A page file, index or store folder under a store — a path, not a title. */
+const STORE_FILE = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?:\.\w+)?|[\w-]+\.json)$/i;
+const keep = (title) => STORE_FILE.test(title);
+// The first segment of a private page's name: `vaults`, or `private` before #1506.
+const SEGMENT = `(?:${PRIVATE_URL_SEGMENT}|${LEGACY_PRIVATE_ROOT})`;
+// URL-encoded: vaults%2F{owner}%2F{store}%2F{title}
+const ENCODED = new RegExp(`(${PRIVATE_URL_SEGMENT}|${LEGACY_PRIVATE_ROOT})%2F([^%\\s/?#&"']+)%2F([^%\\s/?#&"']+)%2F([^\\s/?#&"']+)`, 'gi');
+// A URL path: /vaults/{owner}/{store}/{title}, the title one path segment.
+const URL_PATH = new RegExp(`(\\/${SEGMENT}\\/[^/\\s?#'"]+\\/[^/\\s?#'"]+\\/)([^/\\s?#'"]+)`, 'g');
+// Any private page name at all — the cheap test before the three rewrites.
+const ANY_NAME = new RegExp(`${SEGMENT}(?:\\/|%2F)`, 'i');
+// As written: the title runs to the end of the line, a quote, or where the
+// next `key=` field, `)` or `]` begins. A title containing one of those loses
+// only what follows it — over- rather than under-redaction is not possible
+// without knowing the title, so the boundary is kept deliberately wide.
+const PLAIN = new RegExp(`(^|[^/\\w%])(${SEGMENT}\\/[^/\\s'"]+\\/[^/\\s'"]+\\/)(.+?)(?=$|\\n|"|'(?=[\\s,.;:)\\]]|$)|\\s[\\w.-]+=|\\)|\\])`, 'gm');
+/**
+ * Strike the title from every private page name in `text`.
+ *
+ * @param text - a log line, message or audit field
+ * @returns the text with each private title replaced by `[redacted]`
+ */
+export function redactPrivateNames(text) {
+    if (typeof text !== 'string' || !ANY_NAME.test(text))
+        return text;
+    return text
+        .replace(ENCODED, (whole, segment, owner, store, title) => (keep(title) ? whole : `${segment}%2F${owner}%2F${store}%2F${REDACTED_TITLE}`))
+        .replace(URL_PATH, (whole, prefix, title) => (keep(title) || title === REDACTED_TITLE ? whole : `${prefix}${REDACTED_TITLE}`))
+        .replace(PLAIN, (whole, lead, prefix, title) => (keep(title) || title.startsWith('[redacted') ? whole : `${lead}${prefix}${REDACTED_TITLE}`));
+}
+/**
+ * The same, over every string in a value — an audit event's fields,
+ * metadata and context. Other values are returned as they are.
+ */
+export function redactPrivateNamesDeep(value) {
+    if (typeof value === 'string')
+        return redactPrivateNames(value);
+    if (Array.isArray(value))
+        return value.map(redactPrivateNamesDeep);
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactPrivateNamesDeep(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * Winston format striking private titles from the message, any stack, and
+ * the metadata a line carries (`logger.info(msg, { pageName })`). Placed
+ * before `printf`, beside redactSecretsFormat, so every transport gets it.
+ */
+export function redactPrivateNamesFormat() {
+    return format((info) => {
+        for (const key of Object.keys(info)) {
+            if (key === 'level' || key === 'timestamp')
+                continue;
+            info[key] = redactPrivateNamesDeep(info[key]);
+        }
+        return info;
+    })();
+}

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

@@ -0,0 +1,58 @@
+import type { Logform } from 'winston';
+/** Why a listed key contributed no redaction. */
+export interface SkippedSecret {
+    key: string;
+    reason: 'unset' | 'not-a-string' | 'empty' | 'env-ref' | 'too-short';
+}
+export interface RefreshResult {
+    /** How many values are now being redacted. */
+    active: number;
+    /** Listed keys that contributed nothing, with the reason. */
+    skipped: SkippedSecret[];
+}
+/**
+ * Minimal shape needed from ConfigurationManager, to avoid importing it — that
+ * import is the bootstrap cycle this module exists on the far side of. Matches
+ * `ConfigurationManager.getProperty(key, defaultValue?): unknown` exactly; a
+ * generic signature here would not accept the real manager.
+ */
+export interface SecretConfigReader {
+    getProperty(key: string, defaultValue?: unknown): unknown;
+}
+/**
+ * Rebuild the redaction table from the current configuration.
+ *
+ * Call after ConfigurationManager is initialized, and again after any change to
+ * the secret keys or their values. Safe to call repeatedly — it replaces the
+ * table wholesale rather than accumulating.
+ *
+ * @param configManager anything exposing `getProperty` (ConfigurationManager)
+ * @returns what is now active, and which listed keys were skipped and why
+ */
+export declare function refreshRedactedSecrets(configManager: SecretConfigReader | null | undefined): RefreshResult;
+/** Drop all redactions. Intended for tests. */
+export declare function clearRedactedSecrets(): void;
+/** How many values are currently redacted. Intended for tests/diagnostics. */
+export declare function getRedactedSecretCount(): number;
+/**
+ * Replace every configured secret in `text` with `[redacted:<key>]`.
+ *
+ * The key is named so the line stays diagnosable — "the SMTP password appeared
+ * here" is useful; an anonymous `***` is not.
+ *
+ * Uses split/join rather than a RegExp: secrets routinely contain characters
+ * that are regex metacharacters, and building a pattern from an untrusted-shape
+ * value is how a redactor ends up throwing on the one line that mattered.
+ */
+export declare function redactSecrets(text: string): string;
+/**
+ * Winston format that redacts secrets from the message and any attached stack.
+ *
+ * Place it BEFORE `printf` in the pipeline so it applies once, to every
+ * transport and every consumer, rather than per output target.
+ *
+ * Non-string messages are left alone: the printf stage stringifies them, and
+ * mutating an object's identity mid-pipeline would surprise a structured/JSON
+ * provider. The primary leak shape is an interpolated string.
+ */
+export declare function redactSecretsFormat(): Logform.Format;

package/lib/src/utils/redactSecrets.js

@@ -0,0 +1,171 @@
+/**
+ * redactSecrets — keep configured secrets out of log output (#1030).
+ *
+ * `ngdpbase.config.sensitive-values` (its `secret` entries) already names the values that must never be
+ * shown; it drives masking on `/admin/configuration`. Nothing applied that list
+ * to the logs, so a secret reaching a log line was written in the clear — to
+ * disk, and to `/admin/logs`, which `admin-read` can open. `app.ts` printed the
+ * admin password at startup for exactly this reason (fixed in `2b48d838`). That
+ * one line is closed; this closes the class.
+ *
+ * This is defence in depth, NOT permission to log secrets. It matches literal
+ * occurrences only — a value that has been base64-encoded, URL-embedded, hashed
+ * or paraphrased still gets through. The rule stays "do not log credentials";
+ * this catches the mistakes.
+ *
+ * ## Why the values are pushed in rather than read
+ *
+ * The logger bootstraps at module load, long before WikiEngine or
+ * ConfigurationManager exist, and is imported by nearly every module —
+ * ConfigurationManager included. Reading config from here would create a
+ * bootstrap cycle (see the header of BaseLoggingProvider). So the redaction
+ * table is a module-level set that starts EMPTY and is filled by
+ * {@link refreshRedactedSecrets} once config is resolved, from
+ * `WikiEngine.initialize()`.
+ *
+ * Two consequences worth knowing:
+ *
+ *   - Log lines emitted before that call are not redacted. Nothing has read
+ *     config at that point, so a config-derived secret cannot be in them.
+ *   - The format closure reads the live table on every line, which is what
+ *     makes the deferred fill work at all: `reconfigureLogger()` replaces the
+ *     logger's transports but NOT its format, so the format object created at
+ *     module load is the one still running afterwards.
+ *
+ * For the same cycle reason this module never imports the logger. Callers that
+ * want the skipped keys reported get them back from
+ * {@link refreshRedactedSecrets} and log them themselves.
+ */
+import { format } from 'winston';
+import { secretKeys } from './sensitiveValues.js';
+/**
+ * Values shorter than this are never redacted.
+ *
+ * A short secret would corrupt every line containing it as a substring: were
+ * `defaultpassword` set to `admin`, redaction would mangle the word "admin"
+ * across unrelated output and make the logs useless — while teaching nobody
+ * that the password is weak. Skipping is reported, not silent.
+ */
+const MIN_SECRET_LENGTH = 8;
+/**
+ * Active redactions, longest value first.
+ *
+ * Rebuilt only by {@link refreshRedactedSecrets} — never per log line. This is
+ * a hot path: every line pays one pass per entry.
+ */
+let redactions = [];
+/** Classify a resolved config value, or return null when it is usable. */
+function rejectionReason(value) {
+    if (value === undefined || value === null)
+        return 'unset';
+    if (typeof value !== 'string')
+        return 'not-a-string';
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return 'empty';
+    // `"$NGDPBASE_SMTP_PASS"` in config is a pointer to an env var, not a secret.
+    // The resolved value is what needs redacting; the literal would match the
+    // documentation that explains the convention.
+    if (trimmed.startsWith('$'))
+        return 'env-ref';
+    if (trimmed.length < MIN_SECRET_LENGTH)
+        return 'too-short';
+    return null;
+}
+/**
+ * Rebuild the redaction table from the current configuration.
+ *
+ * Call after ConfigurationManager is initialized, and again after any change to
+ * the secret keys or their values. Safe to call repeatedly — it replaces the
+ * table wholesale rather than accumulating.
+ *
+ * @param configManager anything exposing `getProperty` (ConfigurationManager)
+ * @returns what is now active, and which listed keys were skipped and why
+ */
+export function refreshRedactedSecrets(configManager) {
+    const skipped = [];
+    if (!configManager || typeof configManager.getProperty !== 'function') {
+        redactions = [];
+        return { active: 0, skipped };
+    }
+    const keys = secretKeys((k, d) => configManager.getProperty(k, d));
+    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 reason = rejectionReason(value);
+        if (reason) {
+            skipped.push({ key, reason });
+            continue;
+        }
+        const literal = value.trim();
+        // Two keys holding the same value redact once; the first key names it.
+        if (seen.has(literal))
+            continue;
+        seen.add(literal);
+        next.push({ key, value: literal });
+    }
+    // Longest first: where one secret contains another, the longer must be
+    // struck first or the shorter leaves a mangled remainder of the longer.
+    next.sort((a, b) => b.value.length - a.value.length);
+    redactions = next;
+    return { active: redactions.length, skipped };
+}
+/** Drop all redactions. Intended for tests. */
+export function clearRedactedSecrets() {
+    redactions = [];
+}
+/** How many values are currently redacted. Intended for tests/diagnostics. */
+export function getRedactedSecretCount() {
+    return redactions.length;
+}
+/**
+ * Replace every configured secret in `text` with `[redacted:<key>]`.
+ *
+ * The key is named so the line stays diagnosable — "the SMTP password appeared
+ * here" is useful; an anonymous `***` is not.
+ *
+ * Uses split/join rather than a RegExp: secrets routinely contain characters
+ * that are regex metacharacters, and building a pattern from an untrusted-shape
+ * value is how a redactor ends up throwing on the one line that mattered.
+ */
+export function redactSecrets(text) {
+    if (redactions.length === 0 || typeof text !== 'string' || text === '')
+        return text;
+    let out = text;
+    for (const { key, value } of redactions) {
+        if (out.includes(value))
+            out = out.split(value).join(`[redacted:${key}]`);
+    }
+    return out;
+}
+/**
+ * Winston format that redacts secrets from the message and any attached stack.
+ *
+ * Place it BEFORE `printf` in the pipeline so it applies once, to every
+ * transport and every consumer, rather than per output target.
+ *
+ * Non-string messages are left alone: the printf stage stringifies them, and
+ * mutating an object's identity mid-pipeline would surprise a structured/JSON
+ * provider. The primary leak shape is an interpolated string.
+ */
+export function redactSecretsFormat() {
+    return format((info) => {
+        if (redactions.length === 0)
+            return info;
+        if (typeof info.message === 'string') {
+            info.message = redactSecrets(info.message);
+        }
+        // Error stacks carry the message, so a credential in a thrown error's text
+        // reaches the log through this field rather than `message`.
+        if (typeof info.stack === 'string') {
+            info.stack = redactSecrets(info.stack);
+        }
+        return info;
+    })();
+}