@warlock.js/logger 4.15.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to `@warlock.js/logger` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.0.0 - 2026-08-25
+
+### Changed
+
+- This package is unchanged in 5.0.0; its version moved only because the Warlock family releases in lockstep.
+
+## 4.16.0 - 2026-08-18
+
+### Security
+
+- **Secrets are now redacted by default. This is a behavior change — logs that previously showed these values in cleartext will now show `[REDACTED]`.** Redaction used to be a *tool* (`redact.paths`, entirely opt-in): unless an application configured it, a `password` in `context`, an `authorization` header, or an `apiKey` on a logged `Error` reached every sink — console, log file, JSON log file, Sentry — verbatim. Protection existed only where every call site had been configured correctly, with no signal when one hadn't. It is now a *default*.
+
+  A built-in denylist (`DEFAULT_REDACT_KEYS`) censors matching keys at any depth of `context`, `message`, and an `Error`'s own enumerable properties, applied at the same logger-wide choke point as `redact.paths` — so every channel inherits it, including custom ones. The set covers passwords, shared secrets, tokens (access/refresh/id/CSRF/session), API and private keys, HTTP credential headers (`authorization`, `x-api-key`, `cookie`, `set-cookie`), session IDs, connection strings, and high-sensitivity financial PII (card numbers, CVV, SSN, IBAN).
+
+  Keys are matched **exactly**, after normalizing to lower-case with separators stripped — so one entry covers `apiKey` / `api_key` / `API-KEY` / `x-api-key`. Matching is deliberately not substring-based: `*token*` would also blank `tokenCount` and `passwordUpdatedAt`, which is silent data loss in the one place engineers look when something is broken. The trade is that unusual spellings are missed, which is what `redact.keys` is for.
+
+  Two new knobs on `RedactConfig`, both usable logger-wide or per channel:
+
+  - `keys: string[]` — extra key names, unioned with the built-in set.
+  - `defaultKeys: false` — opt out of the built-in set entirely (restores the pre-4.15.0 behavior). An escape hatch, not a tuning knob; prefer a function `censor` if you need to keep a prefix.
+
+  Existing `redact.paths` config is untouched and keeps working — paths and keys are independent matchers, and both apply. `paths` is now optional, so `redact: { keys: [...] }` alone is valid. The additive-only contract still holds in both directions: a channel can add keys or re-enable defaults, but **cannot** switch off a default the logger-wide config left on; conversely, a logger-wide `defaultKeys: false` is inherited rather than silently re-enabled by any channel that happens to set a `redact` option.
+
+  Paths are evaluated before keys, so a function `censor` on an explicit path still receives the original value rather than a mask, and that leaf is not censored twice.
+
+  Known residual gaps, unchanged by this release and documented on `applyRedact`: secrets interpolated into a `message` *string* (`` `token=${t}` ``) cannot be reached by either matcher; `Map` / `Set` / `Buffer` contents are not traversed; and properties exposed only via getters or non-enumerable descriptors are not walked, so an HTTP client that hides its request config behind a getter can still slip through. Enumerable ones — axios's `.config` / `.response`, which carry the outgoing `Authorization` header — *are* now covered.
+
+### Fixed
+
+- Cloning a log entry for redaction no longer discards an `Error`'s own enumerable properties. Previously, configuring `redact` at all silently reduced every logged `Error` to `message` / `stack` / `name` — dropping `.code` and friends as an unadvertised side effect, and putting `.config.headers.authorization` permanently out of reach of any path pattern. Those properties are now carried through the clone (and censored by the key denylist above). An `Error` subclass whose constructor takes a non-string argument also keeps its `message` instead of being rebuilt as an empty one.
+- The redaction clone no longer expands buffers, typed arrays, `Map`, `Set`, `Promise`, or `RegExp` into plain objects — matching what the code already documented. A `Buffer` in `context` had been rebuilt as a multi-thousand-key index map.
+
+### Dependencies
+
+- Bumped `@mongez/reinforcements` to `^4.0.1`. The major makes `Random.string/nanoid/id/token/uuid` CSPRNG-backed (WebCrypto) and removes `Random.seed()` support. This package uses `Random.string(32)` only for the non-security `logger-<id>` instance identifier; audited for `Random.seed(` with no hits, so no code changes were needed.
+
 ## 4.12.0
 
 ### Changed

package/cjs/index.cjs

@@ -822,40 +822,217 @@ var SentryLog = class extends LogChannel {
 	}
 };
 
+//#endregion
+//#region ../logger/src/redact/default-keys.ts
+/**
+* Built-in secret-key denylist — the redaction floor that applies with no
+* configuration at all.
+*
+* ## Why a default list exists
+*
+* Path-based `redact.paths` is a *tool*; it only protects an application whose
+* every call site was configured correctly, and nothing warns you when one
+* wasn't. The overwhelmingly common leak is mundane and needs no attacker
+* input: `log.error("auth", "login", "failed", { headers: req.headers, body:
+* req.body })` puts a live bearer token and a cleartext password into every
+* sink. A key denylist that runs by default turns redaction from a tool into a
+* default protection.
+*
+* ## Matching semantics — exact, on a normalized key
+*
+* Keys are compared after {@link normalizeRedactKey}: lower-cased with every
+* non-alphanumeric character removed. So one entry covers every spelling
+* convention a codebase might use —
+* `apiKey` / `api_key` / `API-KEY` / `apikey` all normalize to `apikey`.
+*
+* The match is **exact on the normalized key, not a substring**. That is a
+* deliberate trade: substring matching (`*token*`) would also swallow
+* `tokenCount`, `passwordUpdatedAt`, `secretsLoaded` — silent, hard-to-debug
+* data loss in the one place engineers look when something is broken. An exact
+* list is auditable: you can read it and know precisely what disappears. The
+* cost is that unusual spellings are missed, which is why the list carries the
+* concrete wire-format variants that actually show up in HTTP headers
+* (`x-api-key`, `proxy-authorization`, `set-cookie`) and why apps can extend it
+* with `redact.keys`.
+*
+* ## What is deliberately NOT here
+*
+* `key`, `auth`, `hash`, `signature`, `salt`, `id` — all too generic. Each
+* would redact far more non-secret fields than secret ones (`key` alone would
+* blank out every `key` in a keyed collection). Applications that want them
+* add them via `redact.keys`.
+*/
+/**
+* Normalize a key for denylist comparison: lower-case, strip every
+* non-alphanumeric character. Collapses `apiKey`, `api_key`, `API-KEY`,
+* `Api Key` and `apikey` onto a single entry.
+*/
+function normalizeRedactKey(key) {
+	return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+* The default denylist, in source spelling. Anything whose normalized key
+* matches one of these is replaced by the configured censor (`"[REDACTED]"`
+* by default) at any depth of `context`, `message`, or an `Error`'s own
+* enumerable properties.
+*
+* Exported so applications can inspect, log, or build on the exact set they
+* are getting rather than guessing at it.
+*/
+const DEFAULT_REDACT_KEYS = [
+	"password",
+	"passwd",
+	"pwd",
+	"passphrase",
+	"passwordHash",
+	"currentPassword",
+	"newPassword",
+	"passwordConfirmation",
+	"secret",
+	"clientSecret",
+	"appSecret",
+	"apiSecret",
+	"secretKey",
+	"token",
+	"accessToken",
+	"refreshToken",
+	"idToken",
+	"authToken",
+	"apiToken",
+	"bearerToken",
+	"csrfToken",
+	"sessionToken",
+	"resetToken",
+	"verificationToken",
+	"jwt",
+	"otp",
+	"apiKey",
+	"privateKey",
+	"encryptionKey",
+	"signingKey",
+	"authorization",
+	"proxyAuthorization",
+	"x-api-key",
+	"x-auth-token",
+	"cookie",
+	"set-cookie",
+	"sessionId",
+	"credentials",
+	"credential",
+	"connectionString",
+	"creditCard",
+	"creditCardNumber",
+	"cardNumber",
+	"cvv",
+	"cvc",
+	"ssn",
+	"socialSecurityNumber",
+	"iban",
+	"taxId"
+];
+/**
+* The default denylist, pre-normalized. Frozen at module load so the hot path
+* never rebuilds it.
+*/
+const DEFAULT_REDACT_KEY_SET = new Set(DEFAULT_REDACT_KEYS.map(normalizeRedactKey));
+
 //#endregion
 //#region ../logger/src/redact/redact.ts
+const DEFAULT_CENSOR = "[REDACTED]";
+/**
+* Values we copy by reference rather than walking. Expanding these with
+* `Object.keys` would be destructive, not protective — a `Buffer` becomes a
+* multi-thousand-key index map, a `Map`/`Set`/`RegExp` becomes `{}`. Their
+* contents are consequently *not* reachable by redaction; see the residual
+* gaps documented on `applyRedact`.
+*/
+function isOpaque(value) {
+	return ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet || value instanceof Promise || value instanceof RegExp;
+}
 /**
 * Deep-clone a value with structural fidelity for log entries — handles plain
-* objects, arrays, `Date`, `Error`, and primitives. Anything else is copied
-* by reference (we only redact paths through plain objects/arrays anyway,
-* and rebuilding e.g. a `Buffer` would change semantics).
+* objects, arrays, `Date`, `Error`, and primitives. Anything else (buffers,
+* maps, sets, promises, regexes) is copied by reference: we only redact
+* through walkable structures anyway, and rebuilding e.g. a `Buffer` would
+* change semantics.
 *
 * Purpose-built rather than reaching for `structuredClone`: `Error` instances
 * lose their `message`/`stack` under `structuredClone` in some Node versions,
 * and the logger pipeline carries them often.
+*
+* When `redaction` is supplied, keys matching its denylist are censored during
+* the same pass — one traversal, not two.
 */
-function cloneEntry(value, seen = /* @__PURE__ */ new WeakMap()) {
+function cloneEntry(value, seen = /* @__PURE__ */ new WeakMap(), redaction, trail = []) {
 	if (value === null || typeof value !== "object") return value;
-	if (seen.has(value)) return seen.get(value);
+	const asObject = value;
+	if (seen.has(asObject)) return seen.get(asObject);
 	if (value instanceof Date) return new Date(value.getTime());
-	if (value instanceof Error) {
-		const copy = new value.constructor(value.message);
-		copy.stack = value.stack;
-		copy.name = value.name;
-		return copy;
-	}
+	if (isOpaque(asObject)) return value;
+	if (value instanceof Error) return cloneError(value, seen, redaction, trail);
 	if (Array.isArray(value)) {
 		const arr = [];
-		seen.set(value, arr);
-		for (const item of value) arr.push(cloneEntry(item, seen));
+		seen.set(asObject, arr);
+		value.forEach((item, index) => {
+			arr.push(cloneEntry(item, seen, redaction, [...trail, String(index)]));
+		});
 		return arr;
 	}
 	const out = {};
-	seen.set(value, out);
-	for (const key of Object.keys(value)) out[key] = cloneEntry(value[key], seen);
+	seen.set(asObject, out);
+	copyOwnKeys(value, out, seen, redaction, trail);
 	return out;
 }
 /**
+* Copy every own enumerable key from `source` onto `target`, censoring the
+* ones the key denylist matches and recursing into the rest.
+*/
+function copyOwnKeys(source, target, seen, redaction, trail) {
+	for (const key of Object.keys(source)) {
+		const childTrail = [...trail, key];
+		if (redaction && redaction.keys.has(normalizeRedactKey(key)) && !redaction.alreadyCensored.has(childTrail.join("."))) {
+			target[key] = applyCensor(source[key], redaction.censor, childTrail);
+			continue;
+		}
+		target[key] = cloneEntry(source[key], seen, redaction, childTrail);
+	}
+}
+/**
+* Clone an `Error`, preserving its own enumerable properties.
+*
+* Those extra properties matter for redaction: HTTP clients (axios, got)
+* attach `.config`/`.request`/`.response` to the errors they throw, and those
+* routinely carry the *outgoing* `Authorization` header of the failed request.
+* Copying them through the walk is what lets the key denylist reach in and
+* censor them — dropping them instead (the pre-4.15.0 behavior) hid the
+* secret only when redaction happened to be configured, and took `.code` and
+* friends with it.
+*
+* `name`/`message`/`stack` are non-enumerable on `Error`, so they are carried
+* over explicitly.
+*/
+function cloneError(value, seen, redaction, trail) {
+	let copy;
+	try {
+		copy = new value.constructor(value.message);
+	} catch {
+		copy = new Error(value.message);
+	}
+	for (const [key, source] of [
+		["message", value.message],
+		["name", value.name],
+		["stack", value.stack]
+	]) Object.defineProperty(copy, key, {
+		value: source,
+		writable: true,
+		enumerable: false,
+		configurable: true
+	});
+	seen.set(value, copy);
+	copyOwnKeys(value, copy, seen, redaction, trail);
+	return copy;
+}
+/**
 * Apply a single censor decision to a value. String censors are returned
 * verbatim; function censors receive the original value plus the dotted
 * path so callers can implement value-aware redaction (mask all but the
@@ -870,6 +1047,9 @@ function applyCensor(value, censor, path) {
 * replacing matched leaves via `censor`. Operates in place — the caller
 * is responsible for cloning before calling.
 *
+* Every censored leaf's dotted path is recorded in `censored` so a following
+* key-denylist pass can leave it alone.
+*
 * Wildcards:
 * - `*` matches exactly one segment (any key on a plain object, any index
 *   on an array — stringified for the path that's passed to a function
@@ -877,54 +1057,144 @@ function applyCensor(value, censor, path) {
 * - `**` matches zero or more segments greedily; the rest of the pattern
 *   is then attempted at the current level and at every descendant.
 */
-function redactAtPath(target, segments, censor, pathTrail) {
+function redactAtPath(target, segments, censor, pathTrail, censored) {
 	if (target === null || typeof target !== "object") return;
 	if (segments.length === 0) return;
 	const [head, ...rest] = segments;
 	if (head === "**") {
-		if (rest.length > 0) redactAtPath(target, rest, censor, pathTrail);
+		if (rest.length > 0) redactAtPath(target, rest, censor, pathTrail, censored);
 		const keys = Array.isArray(target) ? target.map((_, index) => String(index)) : Object.keys(target);
-		for (const key of keys) redactAtPath(target[key], segments, censor, [...pathTrail, key]);
+		for (const key of keys) redactAtPath(target[key], segments, censor, [...pathTrail, key], censored);
 		return;
 	}
 	const keysToVisit = head === "*" ? Array.isArray(target) ? target.map((_, index) => String(index)) : Object.keys(target) : Array.isArray(target) ? /^\d+$/.test(head) && Number(head) < target.length ? [head] : [] : Object.prototype.hasOwnProperty.call(target, head) ? [head] : [];
-	for (const key of keysToVisit) if (rest.length === 0) target[key] = applyCensor(target[key], censor, [...pathTrail, key]);
-	else redactAtPath(target[key], rest, censor, [...pathTrail, key]);
+	for (const key of keysToVisit) if (rest.length === 0) {
+		const leafTrail = [...pathTrail, key];
+		target[key] = applyCensor(target[key], censor, leafTrail);
+		censored.add(leafTrail.join("."));
+	} else redactAtPath(target[key], rest, censor, [...pathTrail, key], censored);
 }
 /**
-* Produce a new `LoggingData` with every path in `config.paths` replaced
-* by `config.censor`. The original entry is never mutated — channels and
-* other call sites can hold references to the input safely.
+* Cheap pre-scan: does this graph contain any denylisted key at all?
 *
-* No-op (returns the input by reference) when `config` is `undefined` or
-* its `paths` array is empty, so the fast path stays fast.
+* Lets the default-on key pass stay allocation-free for the overwhelming
+* majority of entries, which carry no secrets — we only pay for a clone when
+* there is actually something to censor. Also keeps `applyRedact`'s
+* "returns the input by reference when nothing changed" contract intact.
+*/
+function hasDenylistedKey(value, keys, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value !== "object") return false;
+	const asObject = value;
+	if (seen.has(asObject)) return false;
+	seen.add(asObject);
+	if (value instanceof Date || isOpaque(asObject)) return false;
+	if (Array.isArray(value)) return value.some((item) => hasDenylistedKey(item, keys, seen));
+	for (const key of Object.keys(value)) {
+		if (keys.has(normalizeRedactKey(key))) return true;
+		if (hasDenylistedKey(value[key], keys, seen)) return true;
+	}
+	return false;
+}
+/**
+* Cache of resolved key sets, keyed by the config object they came from.
+* Logger-wide and channel configs are long-lived references, so this makes
+* the per-entry cost a single map lookup. Merged configs (rebuilt per entry
+* by `mergeRedact`) fall out of the `WeakMap` on their own.
+*/
+const keySetCache = /* @__PURE__ */ new WeakMap();
+/**
+* Resolve the effective key denylist for a config: the built-in set (unless
+* `defaultKeys: false`) plus any `keys` the application added.
+*
+* Returns `undefined` only when there is nothing to match — i.e. defaults are
+* explicitly off and no custom keys were supplied.
+*/
+function resolveRedactKeys(config) {
+	const useDefaults = config?.defaultKeys !== false;
+	const extra = config?.keys;
+	if (!extra || extra.length === 0) return useDefaults ? DEFAULT_REDACT_KEY_SET : void 0;
+	const cached = config && keySetCache.get(config);
+	if (cached) return cached;
+	const resolved = new Set(useDefaults ? DEFAULT_REDACT_KEY_SET : []);
+	for (const key of extra) resolved.add(normalizeRedactKey(key));
+	if (config) keySetCache.set(config, resolved);
+	return resolved;
+}
+/**
+* Produce a new `LoggingData` with sensitive data censored:
+*
+* 1. every path in `config.paths` (opt-in globs), then
+* 2. every key matching the denylist — the built-in
+*    {@link DEFAULT_REDACT_KEYS} plus `config.keys`, at any depth of
+*    `context`, `message`, and an `Error`'s own enumerable properties.
+*
+* Step 2 runs **with no config at all**: passing `undefined` still censors
+* `password`, `authorization`, `token`, `apiKey` and friends. Pass
+* `{ defaultKeys: false }` to opt out.
+*
+* Paths run first so a function censor sees the original value rather than a
+* mask; leaves the path pass already censored are skipped by the key pass.
+*
+* The original entry is never mutated — channels and other call sites can
+* hold references to the input safely. Returns the input **by reference**
+* when nothing matched, so the fast path stays allocation-free.
+*
+* ## Residual gaps (by design, documented rather than silently absent)
+*
+* - **Secrets interpolated into a `message` string** (`` `token=${t}` ``)
+*   cannot be reached — neither a path nor a key names a substring.
+* - **`Map`/`Set`/`Buffer` contents** are not traversed (see {@link isOpaque}).
+* - **Non-enumerable / getter-backed properties** are not walked, so an HTTP
+*   client that exposes request config behind a getter still slips through.
+*   Enumerable ones (axios's `.config`, `.response`) *are* covered.
 */
 function applyRedact(data, config) {
-	if (!config || config.paths.length === 0) return data;
-	const censor = config.censor ?? "[REDACTED]";
-	const cloned = cloneEntry(data);
-	for (const pattern of config.paths) {
-		const segments = pattern.split(".").filter((segment) => segment.length > 0);
-		if (segments.length === 0) continue;
-		redactAtPath(cloned, segments, censor, []);
-	}
-	return cloned;
+	const paths = config?.paths ?? [];
+	const keys = resolveRedactKeys(config);
+	if (paths.length === 0 && !keys) return data;
+	const censor = config?.censor ?? DEFAULT_CENSOR;
+	let result = data;
+	const censored = /* @__PURE__ */ new Set();
+	if (paths.length > 0) {
+		result = cloneEntry(data);
+		for (const pattern of paths) {
+			const segments = pattern.split(".").filter((segment) => segment.length > 0);
+			if (segments.length === 0) continue;
+			redactAtPath(result, segments, censor, [], censored);
+		}
+	}
+	if (keys && hasDenylistedKey(result, keys)) result = cloneEntry(result, /* @__PURE__ */ new WeakMap(), {
+		keys,
+		censor,
+		alreadyCensored: censored
+	});
+	return result;
 }
 /**
 * Combine two redact configs into one effective config. Used to merge a
 * channel's additive paths on top of the logger-wide floor.
 *
-* - `paths` are concatenated; duplicates are kept (the matcher tolerates
-*   them, and de-duping cross-config would mask a developer typo).
+* - `paths` and `keys` are concatenated; duplicates are kept (the matcher
+*   tolerates them, and de-duping cross-config would mask a developer typo).
 * - `censor` from the channel wins; falls back to the logger's; falls back
 *   to the default `"[REDACTED]"`.
+* - `defaultKeys` follows the additive-only contract: a channel can turn the
+*   built-in denylist back *on* (`true`) but can never turn off one the
+*   logger-wide floor left enabled. When the channel is silent, the logger's
+*   choice is inherited — opting out logger-wide is not quietly undone by
+*   any channel that happens to set a `redact` option.
 */
 function mergeRedact(base, extra) {
 	if (!base && !extra) return void 0;
-	if (!base) return extra;
+	if (!base) return extra.defaultKeys === false ? {
+		...extra,
+		defaultKeys: true
+	} : extra;
 	if (!extra) return base;
 	return {
-		paths: [...base.paths, ...extra.paths],
+		paths: [...base.paths ?? [], ...extra.paths ?? []],
+		keys: [...base.keys ?? [], ...extra.keys ?? []],
+		defaultKeys: extra.defaultKeys === true ? true : base.defaultKeys,
 		censor: extra.censor ?? base.censor
 	};
 }
@@ -1308,6 +1578,8 @@ function captureAnyUnhandledRejection(options = {}) {
 
 //#endregion
 exports.ConsoleLog = ConsoleLog;
+exports.DEFAULT_REDACT_KEYS = DEFAULT_REDACT_KEYS;
+exports.DEFAULT_REDACT_KEY_SET = DEFAULT_REDACT_KEY_SET;
 exports.FileLog = FileLog;
 exports.JSONFileLog = JSONFileLog;
 exports.LogChannel = LogChannel;
@@ -1318,5 +1590,7 @@ exports.captureAnyUnhandledRejection = captureAnyUnhandledRejection;
 exports.clearMessage = clearMessage;
 exports.log = log;
 exports.mergeRedact = mergeRedact;
+exports.normalizeRedactKey = normalizeRedactKey;
+exports.resolveRedactKeys = resolveRedactKeys;
 exports.safeJsonStringify = safeJsonStringify;
 //# sourceMappingURL=index.cjs.map