RHL-006-refactor(errors): enhance JSON response headers with caching strategy and update tests

lib/api/errors.js

@@ -1,3 +1,8 @@
+// ---------------------------------------------------------------------------
+// Ordner: lib/api
+// Datei: errors.js
+// Relativer Pfad: lib/api/errors.js
+// ---------------------------------------------------------------------------
 /**
  * Central API response helpers for consistent JSON output and standardized errors.
  *
@@ -11,8 +16,22 @@
  * because Next.js route handlers can return any `Response` and it keeps tests simple.
  */
 
-/** Default JSON response headers for all API responses that return JSON. */
-const JSON_HEADERS = { "Content-Type": "application/json" };
+/**
+ * Default JSON response headers for all API responses that return JSON.
+ *
+ * RHL-006 (Caching / Freshness):
+ * - We explicitly disable HTTP caching for ALL JSON API responses by default.
+ * - Reason #1: NAS filesystem contents can change at any time (new scans appear).
+ * - Reason #2: Auth/RBAC-protected responses must never be cached/shared by accident
+ *   (e.g. via browser cache, proxies, reverse proxies, or intermediate gateways).
+ *
+ * If a future endpoint truly needs caching, it should override headers explicitly
+ * at the call site via `json(..., status, { "Cache-Control": "..." })`.
+ */
+const JSON_HEADERS = {
+	"Content-Type": "application/json",
+	"Cache-Control": "no-store",
+};
 
 /**
  * Create a JSON `Response` with the given payload.
@@ -176,3 +195,4 @@ export function withErrorHandling(handler, { logPrefix = "[api]" } = {}) {
 		}
 	};
 }
+// ---------------------------------------------------------------------------

lib/api/errors.test.js

@@ -1,7 +1,12 @@
 /* @vitest-environment node */
 
 import { describe, it, expect } from "vitest";
-import { jsonError, withErrorHandling, badRequest } from "./errors.js";
+import { jsonError, withErrorHandling, badRequest, json } from "./errors.js";
+
+it("json sets Cache-Control: no-store by default (RHL-006)", async () => {
+	const res = json({ ok: true }, 200);
+	expect(res.headers.get("Cache-Control")).toBe("no-store");
+});
 
 describe("lib/api/errors", () => {
 	it("jsonError returns the standardized error shape without details", async () => {