@usequark/quark-core 2.5.7 → 2.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.5.7",
+  "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/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
 // ---------------------------------------------------------------------------