cursedbelt-server 4.43.2 → 4.43.3

package/dist/server/analytics/webAnalytics.d.ts

@@ -116,6 +116,19 @@ export declare const WEB_ANALYTICS_PUBLIC_HOST = "cursedalchemy.com";
  * production `dist` served from `127.0.0.1`, so a production-only injection is still a console
  * error there. The hostname is the honest discriminator, not the build mode.
  *
+ * ## 🔴 Why it is skipped on a GET-only (ctgr) device
+ *
+ * A device in GET-only mode (`cursedbelt-core/ctgr-client`) sits behind something that drops
+ * every non-GET, and the beacon reports with a POST to the page's `/cdn-cgi/rum`. It cannot be
+ * tunnelled the way our own API is — the script is Cloudflare's — so there it only ever failed,
+ * a red line per page view, and recorded nothing. Not loading it loses no data (2026-10-08).
+ *
+ * The guard reads the URL as well as `localStorage.ctgr`: this script runs before the app's
+ * `applyCtgrFromLocation()` has stored a first `?ctgr=t`, so the stored flag alone would still
+ * fire on the visit that turns the mode on — and `?ctgr=f` must win over a flag about to be
+ * cleared. The spellings are `ctgrConfig.ts`'s; `tools/check-web-analytics.ts` EXECUTES every
+ * shell's copy against them.
+ *
  * 🔴 It needs inline script to be permitted on the page. Every shell that carries it already
  * ships one; `apps/vault` does not, serves `script-src 'self'`, and is exempt from the beacon
  * for that reason — see `tools/check-web-analytics.ts`.

package/dist/server/analytics/webAnalytics.js

@@ -123,6 +123,19 @@ export const WEB_ANALYTICS_PUBLIC_HOST = "cursedalchemy.com";
  * production `dist` served from `127.0.0.1`, so a production-only injection is still a console
  * error there. The hostname is the honest discriminator, not the build mode.
  *
+ * ## 🔴 Why it is skipped on a GET-only (ctgr) device
+ *
+ * A device in GET-only mode (`cursedbelt-core/ctgr-client`) sits behind something that drops
+ * every non-GET, and the beacon reports with a POST to the page's `/cdn-cgi/rum`. It cannot be
+ * tunnelled the way our own API is — the script is Cloudflare's — so there it only ever failed,
+ * a red line per page view, and recorded nothing. Not loading it loses no data (2026-10-08).
+ *
+ * The guard reads the URL as well as `localStorage.ctgr`: this script runs before the app's
+ * `applyCtgrFromLocation()` has stored a first `?ctgr=t`, so the stored flag alone would still
+ * fire on the visit that turns the mode on — and `?ctgr=f` must win over a flag about to be
+ * cleared. The spellings are `ctgrConfig.ts`'s; `tools/check-web-analytics.ts` EXECUTES every
+ * shell's copy against them.
+ *
  * 🔴 It needs inline script to be permitted on the page. Every shell that carries it already
  * ships one; `apps/vault` does not, serves `script-src 'self'`, and is exempt from the beacon
  * for that reason — see `tools/check-web-analytics.ts`.
@@ -131,7 +144,13 @@ export function webAnalyticsBootstrap(token = WEB_ANALYTICS_SITE_TOKEN) {
     return [
         "<script>",
         `\tvar host = location.hostname;`,
-        `\tif (host === "${WEB_ANALYTICS_PUBLIC_HOST}" || host.endsWith(".${WEB_ANALYTICS_PUBLIC_HOST}")) {`,
+        `\tvar asked = "";`,
+        "\tvar getOnly = false;",
+        "\ttry {",
+        `\t\tasked = ((/[?&]ctgr=([^&]*)/.exec(location.search) || [])[1] || "").toLowerCase();`,
+        `\t\tgetOnly = /^(t|on|1|yes|true)$/.test(asked) || (!/^(f|off|0|no|false)$/.test(asked) && localStorage.getItem("ctgr") === "on");`,
+        "\t} catch (_e) {}",
+        `\tif (!getOnly && (host === "${WEB_ANALYTICS_PUBLIC_HOST}" || host.endsWith(".${WEB_ANALYTICS_PUBLIC_HOST}"))) {`,
         `\t\tvar beacon = document.createElement("script");`,
         `\t\tbeacon.type = "module";`,
         `\t\tbeacon.src = "${WEB_ANALYTICS_BEACON_SRC}";`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.43.2",
+	"version": "4.43.3",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/server/analytics/webAnalytics.spec.ts

@@ -70,7 +70,10 @@ describe("the fleet's beacon", () => {
  * only shows up at a particular hostname — so a test that merely asserted the string contains
  * "cursedalchemy.com" would pass on a guard with the condition inverted.
  */
-function runBootstrap(hostname: string): { appended: string[]; attrs: Record<string, string> } {
+function runBootstrap(
+	hostname: string,
+	device: { search?: string; stored?: string | null; storageThrows?: boolean } = {},
+): { appended: string[]; attrs: Record<string, string> } {
 	const body = /<script>([\s\S]*)<\/script>/.exec(webAnalyticsBootstrap())?.[1] ?? "";
 	expect(body.trim().length).toBeGreaterThan(0);
 	const appended: string[] = [];
@@ -89,7 +92,13 @@ function runBootstrap(hostname: string): { appended: string[]; attrs: Record<str
 			},
 		},
 	};
-	new Function("location", "document", body)({ hostname }, fakeDocument);
+	const fakeStorage = {
+		getItem(key: string): string | null {
+			if (device.storageThrows) throw new Error("SecurityError");
+			return key === "ctgr" ? (device.stored ?? null) : null;
+		},
+	};
+	new Function("location", "document", "localStorage", body)({ hostname, search: device.search ?? "" }, fakeDocument, fakeStorage);
 	return { appended, attrs };
 }
 
@@ -121,6 +130,40 @@ describe("the hostname guard", () => {
 	});
 });
 
+/**
+ * 🔴 A GET-only device drops the beacon's POST, so the beacon is not loaded there at all — and
+ * the URL counts as well as the stored flag, because this script runs before the app stores it.
+ */
+describe("the GET-only (ctgr) guard", () => {
+	const zone = "desk.cursedalchemy.com";
+
+	test("loads NOTHING on a device whose stored mode is on", () => {
+		expect(runBootstrap(zone, { stored: "on" }).appended).toEqual([]);
+	});
+
+	test("loads NOTHING on the very visit that turns the mode on — before anything is stored", () => {
+		for (const search of ["?ctgr=t", "?ctgr=on", "?ctgr=1", "?ctgr=yes", "?ctgr=TRUE", "?open=sheet:1&ctgr=t"]) {
+			expect(runBootstrap(zone, { search }).appended, search).toEqual([]);
+		}
+	});
+
+	test("`?ctgr=f` wins over a stored flag the app is about to clear", () => {
+		for (const search of ["?ctgr=f", "?ctgr=off", "?ctgr=0", "?a=1&ctgr=no"]) {
+			expect(runBootstrap(zone, { search, stored: "on" }).appended, search).toEqual([WEB_ANALYTICS_BEACON_SRC]);
+		}
+	});
+
+	test("an ordinary visitor still gets the beacon — an unknown value, another key, or storage that throws", () => {
+		for (const device of [{ search: "?ctgr=maybe" }, { search: "?notctgr=t" }, { stored: "off" }, { storageThrows: true }, {}]) {
+			expect(runBootstrap(zone, device).appended, JSON.stringify(device)).toEqual([WEB_ANALYTICS_BEACON_SRC]);
+		}
+	});
+
+	test("turned on by the URL, it holds even where storage throws", () => {
+		expect(runBootstrap(zone, { search: "?ctgr=t", storageThrows: true }).appended).toEqual([]);
+	});
+});
+
 describe("htmlCarriesWebAnalytics", () => {
 	test("true for the bootstrap block a shell actually pastes", () => {
 		expect(htmlCarriesWebAnalytics(webAnalyticsBootstrap())).toBe(true);

package/src/server/analytics/webAnalytics.ts

@@ -135,6 +135,19 @@ export const WEB_ANALYTICS_PUBLIC_HOST = "cursedalchemy.com";
  * production `dist` served from `127.0.0.1`, so a production-only injection is still a console
  * error there. The hostname is the honest discriminator, not the build mode.
  *
+ * ## 🔴 Why it is skipped on a GET-only (ctgr) device
+ *
+ * A device in GET-only mode (`cursedbelt-core/ctgr-client`) sits behind something that drops
+ * every non-GET, and the beacon reports with a POST to the page's `/cdn-cgi/rum`. It cannot be
+ * tunnelled the way our own API is — the script is Cloudflare's — so there it only ever failed,
+ * a red line per page view, and recorded nothing. Not loading it loses no data (2026-10-08).
+ *
+ * The guard reads the URL as well as `localStorage.ctgr`: this script runs before the app's
+ * `applyCtgrFromLocation()` has stored a first `?ctgr=t`, so the stored flag alone would still
+ * fire on the visit that turns the mode on — and `?ctgr=f` must win over a flag about to be
+ * cleared. The spellings are `ctgrConfig.ts`'s; `tools/check-web-analytics.ts` EXECUTES every
+ * shell's copy against them.
+ *
  * 🔴 It needs inline script to be permitted on the page. Every shell that carries it already
  * ships one; `apps/vault` does not, serves `script-src 'self'`, and is exempt from the beacon
  * for that reason — see `tools/check-web-analytics.ts`.
@@ -143,7 +156,13 @@ export function webAnalyticsBootstrap(token: string = WEB_ANALYTICS_SITE_TOKEN):
 	return [
 		"<script>",
 		`\tvar host = location.hostname;`,
-		`\tif (host === "${WEB_ANALYTICS_PUBLIC_HOST}" || host.endsWith(".${WEB_ANALYTICS_PUBLIC_HOST}")) {`,
+		`\tvar asked = "";`,
+		"\tvar getOnly = false;",
+		"\ttry {",
+		`\t\tasked = ((/[?&]ctgr=([^&]*)/.exec(location.search) || [])[1] || "").toLowerCase();`,
+		`\t\tgetOnly = /^(t|on|1|yes|true)$/.test(asked) || (!/^(f|off|0|no|false)$/.test(asked) && localStorage.getItem("ctgr") === "on");`,
+		"\t} catch (_e) {}",
+		`\tif (!getOnly && (host === "${WEB_ANALYTICS_PUBLIC_HOST}" || host.endsWith(".${WEB_ANALYTICS_PUBLIC_HOST}"))) {`,
 		`\t\tvar beacon = document.createElement("script");`,
 		`\t\tbeacon.type = "module";`,
 		`\t\tbeacon.src = "${WEB_ANALYTICS_BEACON_SRC}";`,