@warlock.js/cache 4.15.0 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@warlock.js/cache` 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
+
+- **File driver path traversal (Critical):** cache keys were mapped to on-disk paths with `path.resolve(directory, key)` and no sanitization, so a key containing `../` (reachable through `set`/`get`/`remove`/`removeNamespace`, including keys derived from user input via `cached()` auto-keys) escaped the cache directory and allowed arbitrary file read, write, and recursive delete. The file driver now percent-encodes `%`, `/`, and `\` when mapping a key to its directory (each key becomes exactly one contained directory component; the logical `.`-delimited namespace scheme is unchanged) and additionally asserts the resolved path stays inside the cache root, throwing `CacheError` otherwise. Memory/redis/pg key semantics are unaffected.
+- Redis `removeNamespace` now escapes glob metacharacters (`*`, `?`, `[`, `\`) before building its `KEYS` pattern, so a namespace carrying untrusted input can no longer widen the match and delete keys outside its own prefix.
+- Removed the raw `console.log(value)` dump of the full cached payload when `structuredClone` fails in `parseCachedData` — cached values (potentially PII/tokens) no longer leak to stdout; the structured error log with the value's type is kept.
+- **Credential leak via error logging (Medium):** `logError()` and the Redis driver's `connect()` failure path printed the raw `Error` object straight to stdout (`console.log`) or to `log.fatal`, which could include the connection URL — and password — that some Redis/Node client errors echo back in `error.message`/`cause` on connection failure. Both call sites now go through a new `safeErrorInfo()` helper that logs only a redacted `{ message, code }` shape (never the raw error object), with any `scheme://user:pass@` credentials in the message masked to `scheme://[REDACTED]@`. The bare `console.log(error)`/`console.log("Err", error)` calls are gone entirely.
+- **Redis `removeNamespace` blocking `KEYS` scan (Medium):** replaced the blocking `KEYS` command with a non-blocking `SCAN` cursor loop (`client.scanIterator`), so clearing a namespace on a large keyspace no longer stalls the single-threaded Redis event loop for every other tenant/consumer. The existing glob-escaping fix (above) is unchanged.
+- **File driver `removeNamespace` dotted-key gap (Medium):** dotted keys (`ns.a`) are stored as *sibling* directories under the cache root (see the path-traversal fix above), so removing namespace `ns` — which only ever deleted a directory literally named `ns` — silently left every `ns.*` key on disk. `removeNamespace` now lists the cache root's immediate children, decodes each back to its logical key, and removes every directory whose logical key equals the namespace or starts with `<namespace>.`, matching the boundary semantics the `pg` driver already used for the same contract. Honors `globalPrefix` (previously ignored, so a global flush could wipe the whole cache root instead of scoping to the tenant) and preserves the existing path-containment guard.
+
+### 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; audited this package's source and tests for `Random.seed(` and for seeded/reproducible use of `Random.*`, no hits, so no code changes were needed.
+
 ## 4.2.11
 
 ### Changed

package/cjs/index.cjs

@@ -460,6 +460,36 @@ function cosineSimilarity(a, b) {
 	if (normA === 0 || normB === 0) return 0;
 	return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }
+/**
+* Matches userinfo credentials embedded in a connection URL
+* (e.g. `redis://user:pass@host`). Node/Redis/Postgres client errors
+* frequently echo the target connection string — including the password —
+* back in `error.message` on connection failure.
+*/
+const CREDENTIALS_IN_URL = /(:\/\/)[^\s/@]+:[^\s/@]+@/g;
+/**
+* Strip embedded `user:pass@` credentials from a string before it reaches
+* any log sink.
+*/
+function redactCredentials(message) {
+	return message.replace(CREDENTIALS_IN_URL, "$1[REDACTED]@");
+}
+/**
+* Reduce an unknown thrown value to a log-safe `{ message, code? }` shape.
+* Callers must never log the raw error object itself — it may carry the
+* connection URL (with password) in the top-level message, `cause`, or
+* driver-specific fields, all of which `console.log`/`util.inspect` would
+* still print in full.
+*/
+function safeErrorInfo(error) {
+	if (error instanceof Error) {
+		const info = { message: redactCredentials(error.message) };
+		const code = error.code;
+		if (code) info.code = String(code);
+		return info;
+	}
+	return { message: redactCredentials(String(error)) };
+}
 let CACHE_FOR = /* @__PURE__ */ function(CACHE_FOR) {
 	/**
 	* Cache for 30 Minutes (in seconds)
@@ -2088,10 +2118,15 @@ var BaseCacheDriver = class {
 	}
 	/**
 	* Log error message
+	*
+	* Never logs the raw `error` object — driver connection errors (Redis,
+	* Postgres, ...) can carry the connection string, including the password,
+	* in the message/cause. Only a redacted `{ message, code }` shape is
+	* passed to the structured logger.
 	*/
 	logError(message, error) {
-		_warlock_js_logger.log.error("cache." + this.name, "error", message);
-		if (error) console.log(error);
+		if (error) _warlock_js_logger.log.error("cache." + this.name, "error", message, safeErrorInfo(error));
+		else _warlock_js_logger.log.error("cache." + this.name, "error", message);
 	}
 	/**
 	* Get the default TTL in seconds. Parses human-readable strings (`"1h"`, `"30m"`)
@@ -2137,7 +2172,6 @@ var BaseCacheDriver = class {
 		try {
 			return structuredClone(value);
 		} catch (error) {
-			console.log(value);
 			this.logError(`Failed to clone cached value for ${key}, typeof value: ${typeof value}`, error);
 			throw error;
 		}
@@ -2293,12 +2327,74 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		return "cache.json";
 	}
 	/**
+	* Map a parsed cache key (or namespace) to its on-disk directory.
+	*
+	* The key must become exactly one directory component: `%` and the path
+	* separators are percent-encoded so a hostile key (`../../etc`,
+	* `..\\..\\evil`) turns into an inert directory name instead of a path
+	* traversal, while distinct keys can never collide after encoding. Dots are
+	* left untouched — the `.`-delimited namespace scheme is purely logical and
+	* only ever produces a single filesystem component here.
+	*/
+	keyDirectory(parsedKey) {
+		return this.containedPath(this.encodeKeySegment(parsedKey));
+	}
+	/**
+	* Percent-encode a parsed key into an inert, single-component directory
+	* name. Dots are left untouched — see {@link keyDirectory}.
+	*/
+	encodeKeySegment(parsedKey) {
+		return parsedKey.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/\\/g, "%5C");
+	}
+	/**
+	* Reverse of {@link encodeKeySegment} — recovers the logical, dot-delimited
+	* parsed key from an on-disk directory name. Used by {@link removeNamespace}
+	* to test which sibling directories logically belong to a namespace, since
+	* dotted keys (`ns.a`) are stored as sibling directories rather than nested
+	* ones (see {@link keyDirectory}'s doc comment).
+	*/
+	decodeKeySegment(encoded) {
+		return encoded.replace(/%2F/g, "/").replace(/%5C/g, "\\").replace(/%25/g, "%");
+	}
+	/**
+	* Resolve `segment` against the cache root and throw when the result lands
+	* outside it — the last line of defense against path traversal, independent
+	* of how the key was encoded.
+	*/
+	containedPath(segment) {
+		const base = path.default.resolve(this.directory);
+		const resolved = path.default.resolve(base, segment);
+		const relative = path.default.relative(base, resolved);
+		if (relative === ".." || relative.startsWith(`..${path.default.sep}`) || path.default.isAbsolute(relative)) throw new CacheError(`Cache key resolves outside the cache directory: "${segment}"`);
+		return resolved;
+	}
+	/**
 	* {@inheritdoc}
+	*
+	* Dotted keys (`ns.a`) are stored as sibling directories, not nested ones
+	* (see {@link keyDirectory}) — a directory literally named `<namespace>`
+	* rarely exists on its own. Namespace removal therefore has to scan the
+	* cache root's immediate children and remove every directory whose
+	* *logical* (decoded) name equals the namespace or starts with
+	* `<namespace>.`, mirroring the `key = $1 OR key LIKE $2` boundary
+	* semantics the `pg` driver already uses for the same contract.
 	*/
 	async removeNamespace(namespace) {
+		const parsedNamespace = this.parseKey(namespace);
 		this.log("clearing", namespace);
 		try {
-			await (0, _warlock_js_fs.removeDirectoryAsync)(path.default.resolve(this.directory, namespace));
+			const root = this.containedPath("");
+			if (parsedNamespace === "") {
+				await (0, _warlock_js_fs.removeDirectoryAsync)(root);
+				this.log("cleared", namespace);
+				return this;
+			}
+			const prefix = `${parsedNamespace}.`;
+			const entries = await (0, _warlock_js_fs.listDirectoriesAsync)(root).catch(() => []);
+			await Promise.all(entries.map(async (entryPath) => {
+				const decoded = this.decodeKeySegment(path.default.basename(entryPath));
+				if (decoded === parsedNamespace || decoded.startsWith(prefix)) await (0, _warlock_js_fs.removeDirectoryAsync)(entryPath);
+			}));
 			this.log("cleared", namespace);
 		} catch (error) {}
 		return this;
@@ -2322,7 +2418,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 			existing: null
 		};
 		const data = this.prepareDataForStorage(value, ttl, staleAt);
-		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		const fileDirectory = this.keyDirectory(parsedKey);
 		await (0, _warlock_js_fs.ensureDirectoryAsync)(fileDirectory);
 		await (0, _warlock_js_fs.putJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName), data);
 		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
@@ -2362,7 +2458,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	*/
 	async getEntry(key) {
 		const parsedKey = this.parseKey(key);
-		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		const fileDirectory = this.keyDirectory(parsedKey);
 		try {
 			const entry = await (0, _warlock_js_fs.getJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName));
 			if (!entry) return null;
@@ -2378,7 +2474,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	async get(key) {
 		const parsedKey = this.parseKey(key);
 		this.log("fetching", parsedKey);
-		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		const fileDirectory = this.keyDirectory(parsedKey);
 		try {
 			const value = await (0, _warlock_js_fs.getJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName));
 			const result = await this.parseCachedData(parsedKey, value);
@@ -2401,7 +2497,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	async remove(key) {
 		const parsedKey = this.parseKey(key);
 		this.log("removing", parsedKey);
-		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		const fileDirectory = this.keyDirectory(parsedKey);
 		try {
 			await (0, _warlock_js_fs.removeDirectoryAsync)(fileDirectory);
 			this.log("removed", parsedKey);
@@ -3796,8 +3892,13 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 	async removeNamespace(namespace) {
 		namespace = this.parseKey(namespace);
 		this.log("clearing", namespace);
-		const keys = await this.client?.keys(`${namespace}*`);
-		if (!keys || keys.length === 0) {
+		const pattern = namespace.replace(/[\\*?[\]]/g, "\\$&");
+		const keys = [];
+		if (this.client) for await (const key of this.client.scanIterator({
+			MATCH: `${pattern}*`,
+			COUNT: 100
+		})) keys.push(key);
+		if (keys.length === 0) {
 			this.log("notFound", namespace);
 			return;
 		}
@@ -3967,15 +4068,15 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 			const { createClient } = RedisClient;
 			this.client = createClient(clientOptions);
 			this.client.on("error", (error) => {
-				if (error.code === "ECONNREFUSED") this.log("connectionFailed", error);
-				else this.log("error", error.message);
+				const { message } = safeErrorInfo(error);
+				if (error.code === "ECONNREFUSED") this.log("connectionFailed", message);
+				else this.log("error", message);
 			});
 			await this.client.connect();
 			this.log("connected");
 			await this.emit("connected");
 		} catch (error) {
-			console.log("Err", error);
-			_warlock_js_logger.log.fatal("cache", "redis", error);
+			_warlock_js_logger.log.fatal("cache", "redis", "Failed to connect", safeErrorInfo(error));
 			await this.emit("error", { error });
 		}
 	}
@@ -4088,5 +4189,7 @@ exports.normalizeToOptions = normalizeToOptions;
 exports.normalizeToRememberOptions = normalizeToRememberOptions;
 exports.parseCacheKey = parseCacheKey;
 exports.parseTtl = parseTtl;
+exports.redactCredentials = redactCredentials;
 exports.resolveTtl = resolveTtl;
+exports.safeErrorInfo = safeErrorInfo;
 //# sourceMappingURL=index.cjs.map