@usequark/quark-core 2.5.6 → 2.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.5.6",
+  "version": "2.5.8",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",

package/src/redis.js

@@ -1,3 +1,5 @@
+import { redactUrl } from "./utils.js";
+
 /**
  * Builds REDIS_URL from individual environment variables if not explicitly provided.
  * Allows configuration via individual REDIS_* vars instead of a single REDIS_URL.
@@ -39,6 +41,9 @@ export const createRedisClient = createRedisConfig;
  * Dynamically imports ioredis so it doesn't fail at load time if the package is not installed.
  * Creates a temporary connection, sends PING, expects PONG, then disconnects.
  *
+ * The `message` on the error path is safe to return from an unauthenticated
+ * endpoint: it never contains a password (see `getRedisEndpoint`).
+ *
  * @param {object} [options]
  * @param {number} [options.timeout=3000] - Connection/ping timeout in milliseconds.
  * @returns {Promise<{ status: "ok", latencyMs: number } | { status: "error", message: string }>}
@@ -107,7 +112,7 @@ export async function pingRedis({ timeout = 3000 } = {}) {
 			error?.code === "ECONNREFUSED" ||
 			/connection is closed|ECONNREFUSED/i.test(error?.message ?? "")
 		) {
-			message = `Redis unreachable at ${getRedisUrl()}`;
+			message = `Redis unreachable at ${getRedisEndpoint()}`;
 		} else {
 			message = error?.message ?? String(error);
 		}
@@ -121,6 +126,31 @@ export async function pingRedis({ timeout = 3000 } = {}) {
 	}
 }
 
+/**
+ * Returns the Redis endpoint as `host:port`, with every credential removed.
+ *
+ * The message from `pingRedis` is returned verbatim by the unauthenticated
+ * `/api/health` route, so it must never carry a password. `getRedisUrl()` is
+ * deliberately not used for this: callers need the working connection string,
+ * and it embeds `REDIS_URL` credentials as-is.
+ *
+ * @returns {string} e.g. `redis.railway.internal:6379`
+ */
+export function getRedisEndpoint() {
+	const url = getRedisUrl();
+
+	try {
+		const parsed = new URL(url);
+		const port =
+			parsed.port || (parsed.protocol === "rediss:" ? "6380" : "6379");
+		return `${parsed.hostname}:${port}`;
+	} catch {
+		// Malformed REDIS_URL — fall back to whatever credentials-safe form the
+		// redaction pass can produce rather than echoing the raw value.
+		return redactUrl(url);
+	}
+}
+
 /**
  * Resolves Redis connection config as an ioredis-compatible options object.
  * Precedence: explicit override > REDIS_URL > REDIS_HOST/REDIS_PORT > localhost defaults.

package/src/redis.test.js

@@ -1,6 +1,10 @@
 import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, it } from "node:test";
-import { getRedisUrl, resolveRedisConnection } from "./redis.js";
+import {
+	getRedisEndpoint,
+	getRedisUrl,
+	resolveRedisConnection,
+} from "./redis.js";
 
 describe("getRedisUrl", () => {
 	let originalEnv;
@@ -148,3 +152,61 @@ describe("resolveRedisConnection", () => {
 		assert.equal(result.port, 6382);
 	});
 });
+
+describe("getRedisEndpoint", () => {
+	let originalEnv;
+
+	beforeEach(() => {
+		originalEnv = { ...process.env };
+	});
+
+	afterEach(() => {
+		process.env = originalEnv;
+	});
+
+	it("never returns the password from REDIS_URL", () => {
+		process.env.REDIS_URL = "redis://default:hunter2@cache.internal:6379";
+
+		const endpoint = getRedisEndpoint();
+
+		assert.equal(endpoint, "cache.internal:6379");
+		assert.ok(!endpoint.includes("hunter2"), "endpoint leaked the password");
+		assert.ok(!endpoint.includes("default"), "endpoint leaked the username");
+	});
+
+	it("never returns a password-only credential", () => {
+		process.env.REDIS_URL = "redis://:hunter2@cache.internal:6379";
+
+		const endpoint = getRedisEndpoint();
+
+		assert.equal(endpoint, "cache.internal:6379");
+		assert.ok(!endpoint.includes("hunter2"), "endpoint leaked the password");
+	});
+
+	it("defaults the port to 6379, or 6380 for rediss://", () => {
+		process.env.REDIS_URL = "redis://user:pw@cache.internal";
+		assert.equal(getRedisEndpoint(), "cache.internal:6379");
+
+		process.env.REDIS_URL = "rediss://user:pw@secure.internal";
+		assert.equal(getRedisEndpoint(), "secure.internal:6380");
+	});
+
+	it("reads host and port from REDIS_HOST/REDIS_PORT when REDIS_URL is unset", () => {
+		delete process.env.REDIS_URL;
+		process.env.REDIS_HOST = "cache.internal";
+		process.env.REDIS_PORT = "6390";
+
+		assert.equal(getRedisEndpoint(), "cache.internal:6390");
+	});
+
+	it("does not leak a password out of a URL it cannot parse", () => {
+		process.env.REDIS_URL = "redis://user:hunter2@cache internal:6379";
+
+		const endpoint = getRedisEndpoint();
+
+		assert.ok(
+			!endpoint.includes("hunter2"),
+			`unparseable REDIS_URL leaked its password: ${endpoint}`,
+		);
+	});
+});

package/src/storage.js

@@ -187,11 +187,16 @@ export function generateStorageKey(originalFilename, options = {}) {
  *
  * Checks `ASSET_CDN_URL` first - if set, prepends it to the key.
  * This is provider-agnostic: works with any CDN (CloudFront, Cloudflare,
- * Bunny, Fastly, etc.) as long as the CDN is pointed at the same bucket.
+ * Bunny, Fastly, etc.) provided the CDN is rooted at the bucket, so that a
+ * request for `<cdn>/<key>` maps to the object stored at `<key>`. That is the
+ * standard arrangement for a CDN in front of a bucket and needs no rewrite
+ * rules. If your CDN is not bucket-rooted, set `S3_PUBLIC_URL` instead and use
+ * the S3 adapter's `getPublicUrl()`.
  *
  * Falls back to the local API route (`/api/files/<key>`) when no CDN is
  * configured - covers local development and any environment where
- * `STORAGE_PROVIDER=local` is used.
+ * `STORAGE_PROVIDER=local` is used. The scaffolded `/api/files/[id]` route
+ * accepts a storage key as well as a database id, so this resolves.
  *
  * @param {string} key - Storage key (e.g. "uploads/2026/02/abc-photo.jpg")
  * @returns {string} Full CDN URL or local API route

package/src/storage.test.js

@@ -351,6 +351,55 @@ test("getAssetUrl - percent-encodes key in fallback URL", () => {
 	assert.strictEqual(url, "/api/files/uploads%2Ffile%20with%20spaces.jpg");
 });
 
+// ─── getAssetUrl / route contract ────────────────────────────────────────────
+//
+// The scaffolded GET /api/files/[id] route used to look up by database id only,
+// so every URL this function produced resolved to a 404. It now also resolves a
+// storage key. These tests pin the two halves of that contract from each side:
+// the shape produced here, and the lookup performed by the route (in
+// apps/web/src/app/api/files/[id]/route.test.js).
+test("getAssetUrl - fallback URL carries the key in a single path segment", () => {
+	delete process.env.ASSET_CDN_URL;
+	const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+
+	// A key with slashes must stay inside ONE path segment, or the request never
+	// reaches the [id] route at all — it 404s as an unrouted path. `URL` keeps the
+	// percent-encoding in `pathname`, so it is the encoded slashes that hold the
+	// segment together.
+	const segments = new URL(url, "http://localhost").pathname.split("/");
+	assert.strictEqual(
+		segments.length,
+		4,
+		`key leaked into extra segments: ${url}`,
+	);
+	assert.strictEqual(segments[3], "uploads%2F2026%2F02%2Fabc-photo.jpg");
+	// And it must decode back to exactly the key, which is what the route looks up.
+	assert.strictEqual(
+		decodeURIComponent(segments[3]),
+		"uploads/2026/02/abc-photo.jpg",
+	);
+});
+
+test("getAssetUrl - CDN URL leaves the key path unencoded", () => {
+	// The CDN branch is a real URL space, not a path segment: encoding the slashes
+	// would ask the CDN for a single object literally named "uploads/2026/02/...".
+	// A bucket-rooted CDN maps the path straight onto the key.
+	process.env.ASSET_CDN_URL = "https://assets.example.com";
+	try {
+		const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+		assert.strictEqual(
+			url,
+			"https://assets.example.com/uploads/2026/02/abc-photo.jpg",
+		);
+		assert.ok(
+			!url.includes("%2F"),
+			"CDN URL must not percent-encode the key path",
+		);
+	} finally {
+		delete process.env.ASSET_CDN_URL;
+	}
+});
+
 // ---------------------------------------------------------------------------
 // getSignedUploadUrl
 // ---------------------------------------------------------------------------

package/src/utils.js

@@ -217,3 +217,44 @@ export const memoize = (fn, ttl = 0) => {
 		return value;
 	};
 };
+
+/** Placeholder written over a credential segment. No brackets — the URL
+ * serializer would percent-encode them into `%5BREDACTED%5D`. */
+const REDACTED_CREDENTIAL = "REDACTED";
+
+/**
+ * Strips credentials from a URL so it is safe to log or return from an
+ * unauthenticated endpoint.
+ *
+ * Connection strings reach places the process cannot control: `/api/health`
+ * has no auth and echoes the message from a failed probe, and startup logs end
+ * up in a log aggregator. `redis://default:hunter2@cache.internal:6379` in any
+ * of those is a credential disclosure, so nothing that embeds a URL in a
+ * message should skip this.
+ *
+ * Parseable URLs are rewritten field by field. Anything else is run through a
+ * regex that strips the userinfo segment of a URL-shaped string. A string that
+ * matches neither has no recognisable credential segment and is returned
+ * unchanged.
+ *
+ * @param {string} url
+ * @returns {string} The URL with any username/password replaced
+ */
+export const redactUrl = (url) => {
+	if (typeof url !== "string" || url.length === 0) return url;
+
+	try {
+		const parsed = new URL(url);
+
+		if (!parsed.username && !parsed.password) return url;
+
+		parsed.username = parsed.username ? REDACTED_CREDENTIAL : "";
+		parsed.password = parsed.password ? REDACTED_CREDENTIAL : "";
+		return parsed.toString();
+	} catch {
+		return url.replace(
+			/^([a-z][a-z0-9+.-]*:\/\/)[^/?#@]*@/i,
+			`$1${REDACTED_CREDENTIAL}@`,
+		);
+	}
+};

package/src/utils.test.js

@@ -8,6 +8,7 @@ import {
 	memoize,
 	normalizeErrorMessage,
 	randomString,
+	redactUrl,
 	retryAsync,
 	sanitizeId,
 	sleep,
@@ -191,3 +192,50 @@ test("Utils Module", async (t) => {
 		}, 50);
 	});
 });
+
+test("redactUrl", async (t) => {
+	await t.test("strips username and password from a parseable URL", () => {
+		const result = redactUrl("redis://default:hunter2@cache.internal:6379");
+
+		assert(!result.includes("hunter2"), `password leaked: ${result}`);
+		assert(!result.includes("default"), `username leaked: ${result}`);
+		assert(result.includes("cache.internal"));
+		assert(result.includes("6379"));
+	});
+
+	await t.test("strips a password-only credential", () => {
+		const result = redactUrl("redis://:hunter2@cache.internal:6379");
+
+		assert(!result.includes("hunter2"), `password leaked: ${result}`);
+		assert(result.includes("cache.internal"));
+	});
+
+	await t.test("strips credentials from a postgres URL", () => {
+		const result = redactUrl(
+			"postgresql://app:s3cret@db.internal:5432/app?schema=public",
+		);
+
+		assert(!result.includes("s3cret"), `password leaked: ${result}`);
+		assert(result.includes("db.internal"));
+		assert(result.includes("schema=public"));
+	});
+
+	await t.test("redacts the userinfo of a URL it cannot parse", () => {
+		const result = redactUrl("redis://user:hunter2@cache internal:6379");
+
+		assert(!result.includes("hunter2"), `password leaked: ${result}`);
+	});
+
+	await t.test("leaves a credential-free URL untouched", () => {
+		const url = "redis://cache.internal:6379";
+
+		assert(redactUrl(url) === url);
+	});
+
+	await t.test("passes through non-URL and empty values", () => {
+		assert(redactUrl("not-a-url") === "not-a-url");
+		assert(redactUrl("") === "");
+		assert(redactUrl(undefined) === undefined);
+		assert(redactUrl(null) === null);
+	});
+});