cursedbelt-server 4.3.0 → 4.5.0

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * A public subpath must not STATICALLY drag an OPTIONAL peer, because a static import is
+ * paid at import time by every consumer — including the ones that will never call it.
+ *
+ * ## 🔴 This is the same defect for the THIRD time, and the first two are why the rule is
+ * a check rather than a sentence
+ *
+ * `cursedbelt/src/barrelsReachNoOptionalPeer.spec.ts` carries the full history; the short
+ * version is that `apps/collections` once imported a TYPE from `cursedbelt/server/storage`
+ * and paid for it with `error: Cannot find package 'otplib'` and four dead route suites,
+ * because the barrel reached `streamToken.ts` → the `../auth` index → `totp.ts` → an
+ * optional peer. The app installed a one-time-password library to satisfy a claim shape.
+ *
+ * When the server tier split into this package (task 148), the RUNTIME-FIXTURE half came
+ * with it as `leafSubpathsImportNothing.spec.ts` — but that spec proves what a declared
+ * ZERO-RUNTIME LEAF pulls in, and a barrel is neither. So the barrel half stayed behind in
+ * `cursedbelt`, pointed at `./react`, and **this package shipped with no barrel check at
+ * all.**
+ *
+ * 🔴 It cost exactly what the first two cost, measured 2026-09-18 against the PUBLISHED
+ * `cursedbelt-server@4.3.0` tarball in a clean directory:
+ *
+ *     $ bun add cursedbelt-server && bun -e 'import "cursedbelt-server/d1"'
+ *     error: Cannot find package 'kysely' from …/src/server/d1/kysely.ts
+ *
+ * `./d1`'s index re-exported `./kysely`, which statically imports real VALUES from
+ * `kysely` (`Kysely`, `SqliteAdapter`, `SqliteQueryCompiler` — not types, so they cannot be
+ * erased). `kysely` is an optional peer. So the D1 seam — the thing the whole fleet is
+ * meant to port ONTO — could not be imported by any app that had not already installed a
+ * query builder, which by `../db/kysely.ts`'s own header is most of them: *"Business /
+ * `data JSON` tables stay on raw `db.query()` — do NOT add them here"*. The seam was
+ * unusable by precisely the apps it was built for.
+ *
+ * The fix was to give `createD1Kysely` its own subpath (`./d1/kysely`) and take it out of
+ * the barrel. This spec is what stops the fourth occurrence.
+ *
+ * ## What it measures
+ *
+ * Every subpath in the `exports` map is bundled with bare imports left external, and the
+ * remaining static specifiers are read out of the emitted JS. A DYNAMIC `await
+ * import('sharp')` inside the function that needs it matches neither branch of
+ * {@link STATIC_SPECIFIER} and must not — that is the lazy shape this file exists to
+ * permit, not forbid.
+ *
+ * ## Verified failing before it was trusted (2026-09-18)
+ *
+ *   · re-adding `export … from './kysely'` to `src/server/d1/index.ts`
+ *       → red: "./d1 statically drags optional peer(s): kysely"
+ *   · adding `import 'plainjob';` to `src/server/d1/local.ts` — two hops out of the
+ *     barrel, which grepping the index file cannot see
+ *       → red identically. That is the branch that matters.
+ *   · removing `'./jobs'` from {@link MAY_DRAG} → red, proving the allowlist is load-bearing
+ *     rather than decorative.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * The subpaths whose whole PURPOSE is the optional peer they pull, mapped to what they are
+ * allowed to pull and why. An entry here is a promise that the peer is the point of the
+ * subpath — not a place to park a new drag.
+ *
+ * 🔴 Measured 2026-09-18: these three are the ONLY subpaths in the map that reach an
+ * optional peer. Everything else is clean, which is what makes this list an allowlist
+ * rather than a baseline — it can only shrink.
+ */
+const MAY_DRAG: Record<string, readonly string[]> = {
+	// The whole-package barrel. It exists to re-export everything, so it necessarily reaches
+	// what the specific subpaths reach. An app importing `cursedbelt-server` whole is asking
+	// for that; an app importing `cursedbelt-server/d1` is not, and that is the distinction
+	// this spec protects.
+	'.': ['kysely', 'kysely-bun-sqlite', 'otplib', 'plainjob'],
+	// `createD1Kysely` IS the kysely adapter. Split out of `./d1` on 2026-09-18 precisely so
+	// the seam itself stops paying for it — see the header.
+	'./d1/kysely': ['kysely'],
+	// The job queue is plainjob. Nothing else here is.
+	'./jobs': ['plainjob'],
+};
+
+const OPTIONAL_PEERS = new Set(
+	Object.entries(
+		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},
+	)
+		.filter(([, meta]) => meta?.optional === true)
+		.map(([name]) => name),
+);
+
+/**
+ * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.
+ *
+ * Anchored on the `from` clause rather than on a line starting with `import`, so a
+ * multi-line named import still counts — bun emits `import {\n … \n} from "pkg";` and a
+ * line-anchored pattern silently misses it. A dynamic `import("pkg")` matches neither
+ * branch, which is deliberate.
+ */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+/** `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`. */
+const packageOf = (specifier: string): string | undefined => {
+	const parts = specifier.split('/');
+	return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/**
+ * Bundle one entry and return the bare packages it still imports.
+ *
+ * 🔴 A bundle that did not happen must never read as a subpath that pulls nothing, so a
+ * non-zero exit or an empty bundle THROWS rather than returning an empty set. That is the
+ * one way a check like this dies quietly.
+ */
+const staticExternalsOf = (entry: string, subpath: string): Set<string> => {
+	const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-server-barrel-scan/${subpath.replace(/[^a-z0-9]+/gi, '-')}`;
+	const build = Bun.spawnSync(['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir], {
+		cwd: REPO,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+	const emitted = [...new Bun.Glob('**/*.js').scanSync({ cwd: outdir, onlyFiles: true })];
+	const bundle = emitted.map((f) => readFileSync(`${outdir}/${f}`, 'utf8')).join('\n');
+	if (build.exitCode !== 0 || bundle.trim() === '') {
+		throw new Error(
+			`could not bundle ${subpath} (${entry}, exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
+		);
+	}
+	const found = new Set<string>();
+	for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
+		const specifier = match[1] ?? match[2];
+		if (specifier === undefined || specifier.startsWith('.') || specifier.startsWith('bun:')) continue;
+		const name = packageOf(specifier);
+		if (name !== undefined) found.add(name);
+	}
+	return found;
+};
+
+/** Every subpath with a `source` entry — the ones whose real graph can be measured. */
+const SUBPATHS = Object.entries(pkg.exports as Record<string, { source?: string }>)
+	.filter(([, e]) => typeof e?.source === 'string' && /\.tsx?$/.test(e.source))
+	.map(([subpath, e]) => ({ subpath, entry: (e as { source: string }).source }));
+
+describe('no public subpath statically drags an optional peer', () => {
+	it('measures a non-trivial number of subpaths, so a broken exports map cannot pass vacuously', () => {
+		expect(SUBPATHS.length).toBeGreaterThan(20);
+		expect(OPTIONAL_PEERS.size).toBeGreaterThan(0);
+	});
+
+	for (const { subpath, entry } of SUBPATHS) {
+		const allowed = MAY_DRAG[subpath] ?? [];
+		it(`${subpath} drags ${allowed.length === 0 ? 'no optional peer' : allowed.join(' + ') + ' and nothing more'}`, () => {
+			const dragged = [...staticExternalsOf(entry, subpath)].filter((n) => OPTIONAL_PEERS.has(n)).sort();
+			const unexpected = dragged.filter((n) => !allowed.includes(n));
+			expect(
+				unexpected,
+				`${subpath} statically drags optional peer(s): ${unexpected.join(', ')}\n` +
+					`  Every app importing '${pkg.name}${subpath.slice(1)}' must now install them or crash on import.\n` +
+					`  Give the adapter its own subpath and take it out of this barrel — see ./d1/kysely, which is\n` +
+					`  exactly this fix applied on 2026-09-18 after the published 4.3.0 could not be imported at all.`,
+			).toEqual([]);
+
+			// The allowlist may only shrink: an entry that no longer drags what it promised is
+			// a stale exception, and a stale exception is how a list like this stops meaning
+			// anything.
+			const stale = allowed.filter((n) => !dragged.includes(n));
+			expect(stale, `${subpath} is allowed to drag ${stale.join(', ')} but no longer does — remove the exception`).toEqual(
+				[],
+			);
+		});
+	}
+});

package/src/server/analytics/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `cursedbelt-server/analytics` — where the fleet's web-analytics beacon is DEFINED, and the
+ * invariant that decides which responses may carry it.
+ *
+ * Two files, and the pairing is the point:
+ *
+ *  · `webAnalytics.ts` is the one copy of the tag. An app's public shell pastes it; nothing
+ *    generates ten of them.
+ *  · `injectedScripts.ts` is the general rule — nothing that arrives in a response's HTML may
+ *    be refused by the CSP on that same response — which is what makes "the wall never carries
+ *    the beacon" a CHECK rather than a sentence. `../master-lock/beaconNeverReachesTheWall.spec.ts`
+ *    is that check.
+ *
+ * Both are pure string work with no imports at all, so this subpath costs a consumer nothing
+ * and drags no peer.
+ */
+export {
+	type InjectedScript,
+	foreignScriptSources,
+	scriptsRefusedByCsp,
+} from "./injectedScripts";
+export {
+	WEB_ANALYTICS_BEACON_ORIGIN,
+	WEB_ANALYTICS_BEACON_SRC,
+	WEB_ANALYTICS_SITE_TAG,
+	WEB_ANALYTICS_SITE_TOKEN,
+	WEB_ANALYTICS_TAG,
+	htmlCarriesWebAnalytics,
+	webAnalyticsTag,
+} from "./webAnalytics";

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

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import { foreignScriptSources, scriptsRefusedByCsp } from "./injectedScripts";
+import { WEB_ANALYTICS_BEACON_ORIGIN, WEB_ANALYTICS_TAG } from "./webAnalytics";
+
+const PAGE = "https://collections.cursedalchemy.com/";
+
+/**
+ * The tag Cloudflare's Automatic Setup appended, byte-for-byte as the zone emitted it on
+ * 2026-09-18 — pinned path, integrity hash, `crossorigin` and all. It is kept in its
+ * AUTOMATIC spelling on purpose: this is the shape that was arriving unasked-for, and a
+ * checker that only recognised the manual snippet would go quiet the moment somebody turned
+ * auto-install back on.
+ */
+const BEACON =
+	`<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js/v31edd6df95cf4e85bb4c19e7a9bdbcba1788362987495"` +
+	` integrity="sha512-iIg7k2xntmwu6/uSb5tpc/hySgZc4eoL31yB29W6tJFo2akwjPWcEqnCEdJvGexCL0KEQwVYv5BlowfhVz26hg=="` +
+	` data-cf-beacon='{"version":"2024.11.0","token":"bd88d63678b64bc89f9702f48846bc88","r":1,"spa":2}' crossorigin="anonymous"></script>`;
+
+/** A real app shell: one inline script, one same-origin module. Neither is foreign. */
+const SHELL = `<!doctype html><html><head>
+	<script>try { document.documentElement.classList.toggle("dark", true); } catch (e) {}</script>
+	<script type="module" crossorigin src="/assets/index-edXXbfEe.js"></script>
+</head><body><div id="root"></div></body></html>`;
+
+describe("foreignScriptSources", () => {
+	test("an app's own shell has none — inline and same-origin are not findings", () => {
+		expect(foreignScriptSources(SHELL, PAGE)).toEqual([]);
+	});
+
+	test("finds the beacon the edge appended, single-quoted attribute and all", () => {
+		const found = foreignScriptSources(SHELL.replace("</head>", `${BEACON}</head>`), PAGE);
+		expect(found).toHaveLength(1);
+		expect(found[0]?.origin).toBe(WEB_ANALYTICS_BEACON_ORIGIN);
+	});
+
+	test("the MANUAL snippet is found too, and names the same origin", () => {
+		const found = foreignScriptSources(SHELL.replace("</head>", `${WEB_ANALYTICS_TAG}</head>`), PAGE);
+		expect(found).toHaveLength(1);
+		expect(found[0]?.origin).toBe(WEB_ANALYTICS_BEACON_ORIGIN);
+	});
+
+	test("an absolute URL back to this app's own origin is not foreign", () => {
+		const html = `<script src="https://collections.cursedalchemy.com/assets/x.js"></script>`;
+		expect(foreignScriptSources(html, PAGE)).toEqual([]);
+	});
+
+	test("data: and blob: sources are skipped — no host was injected", () => {
+		const html = `<script src="data:text/javascript,void 0"></script><script src=blob:https://x/y></script>`;
+		expect(foreignScriptSources(html, PAGE)).toEqual([]);
+	});
+
+	test("two tags naming the same foreign origin are reported once per src", () => {
+		const html = `${BEACON}${BEACON}<script src="https://static.cloudflareinsights.com/other.js"></script>`;
+		expect(foreignScriptSources(html, PAGE)).toHaveLength(2);
+	});
+});
+
+describe("scriptsRefusedByCsp", () => {
+	const beacon = foreignScriptSources(BEACON, PAGE);
+
+	/**
+	 * 🔴 The failure path this whole file exists for — the owner's console line, turned into a
+	 * refusal. `script-src 'self'` with something injecting is exactly what he pasted.
+	 */
+	test("script-src 'self' refuses the injected beacon and names its origin", () => {
+		const refused = scriptsRefusedByCsp(
+			"default-src 'none'; style-src 'self'; script-src 'self'; connect-src 'self'; " +
+				"img-src data:; form-action 'none'; base-uri 'none'; frame-ancestors 'none'",
+			beacon,
+			PAGE,
+		);
+		expect(refused.map((s) => s.origin)).toEqual([WEB_ANALYTICS_BEACON_ORIGIN]);
+	});
+
+	test("allowing the host in script-src clears it", () => {
+		const csp = "default-src 'none'; script-src 'self' https://static.cloudflareinsights.com";
+		expect(scriptsRefusedByCsp(csp, beacon, PAGE)).toEqual([]);
+	});
+
+	test("a wildcard subdomain source clears it", () => {
+		expect(scriptsRefusedByCsp("script-src 'self' *.cloudflareinsights.com", beacon, PAGE)).toEqual(
+			[],
+		);
+	});
+
+	test("no CSP header at all refuses nothing — today's public shell", () => {
+		expect(scriptsRefusedByCsp(null, beacon, PAGE)).toEqual([]);
+		expect(scriptsRefusedByCsp("", beacon, PAGE)).toEqual([]);
+	});
+
+	test("a CSP with no script directive and no default-src refuses nothing", () => {
+		expect(scriptsRefusedByCsp("frame-ancestors 'none'; base-uri 'none'", beacon, PAGE)).toEqual([]);
+	});
+
+	test("default-src is the fallback when script-src is absent", () => {
+		expect(scriptsRefusedByCsp("default-src 'self'", beacon, PAGE)).toHaveLength(1);
+		expect(scriptsRefusedByCsp("default-src https:", beacon, PAGE)).toEqual([]);
+	});
+
+	test("script-src-elem wins over script-src, which wins over default-src", () => {
+		const csp =
+			"default-src 'none'; script-src 'self'; script-src-elem https://static.cloudflareinsights.com";
+		expect(scriptsRefusedByCsp(csp, beacon, PAGE)).toEqual([]);
+		expect(scriptsRefusedByCsp("default-src https:; script-src 'self'", beacon, PAGE)).toHaveLength(
+			1,
+		);
+	});
+
+	test("'none' admits nothing, even alongside a scheme in another directive", () => {
+		expect(scriptsRefusedByCsp("script-src 'none'", beacon, PAGE)).toHaveLength(1);
+	});
+
+	test("a scheme source only matches its own scheme", () => {
+		expect(scriptsRefusedByCsp("script-src http:", beacon, PAGE)).toHaveLength(1);
+		expect(scriptsRefusedByCsp("script-src https:", beacon, PAGE)).toEqual([]);
+	});
+
+	test("an http:// host source does not admit an https origin", () => {
+		expect(
+			scriptsRefusedByCsp("script-src http://static.cloudflareinsights.com", beacon, PAGE),
+		).toHaveLength(1);
+	});
+
+	test("a port or path on the source narrows nothing — the conservative direction", () => {
+		const csp = "script-src https://static.cloudflareinsights.com:443/beacon.min.js";
+		expect(scriptsRefusedByCsp(csp, beacon, PAGE)).toEqual([]);
+	});
+
+	test("'strict-dynamic' is undecidable from markup, so it permits", () => {
+		expect(scriptsRefusedByCsp("script-src 'self' 'strict-dynamic' 'nonce-abc'", beacon, PAGE)).toEqual(
+			[],
+		);
+	});
+
+	test("* permits, and 'self' still matches this app's own origin", () => {
+		expect(scriptsRefusedByCsp("script-src *", beacon, PAGE)).toEqual([]);
+		const own = [{ src: "/assets/x.js", origin: "https://collections.cursedalchemy.com" }];
+		expect(scriptsRefusedByCsp("script-src 'self'", own, PAGE)).toEqual([]);
+	});
+
+	test("nothing injected means nothing refused, however strict the policy", () => {
+		expect(scriptsRefusedByCsp("script-src 'none'", [], PAGE)).toEqual([]);
+	});
+});

package/src/server/analytics/injectedScripts.ts

@@ -0,0 +1,139 @@
+/**
+ * Does a page's own CSP refuse a script that arrived in that page's own HTML?
+ *
+ * ## The invariant, which names no vendor
+ *
+ * > No script that reaches the browser inside a response's HTML may be refused by the CSP on
+ * > that same response.
+ *
+ * Every part of the arrangement may move and this stays right. Turn an edge injection off and
+ * the foreign scripts disappear — green. Decide a third-party script is wanted and allow its
+ * host — green. Harden a page with `script-src 'self'` while something is still injecting into
+ * it — RED, and it names the origin, which is the console line the owner would otherwise find
+ * himself during an incident.
+ *
+ * ## 🔴 Why it lives in this package
+ *
+ * It was written in `apps/collections` on 2026-09-18 and it was right there, but it could only
+ * ever see one app — and the response it was written about, the master-lock wall, is served by
+ * THIS package to every app that mounts the guard. One copy here is what makes the two halves
+ * of `webAnalytics.ts`'s decision checkable in the same place: the wall refuses the beacon, and
+ * a public shell carries it.
+ *
+ * ## 🔴 Conservative on purpose
+ *
+ * Every ambiguity resolves to PERMITTED. A source expression this file cannot parse, a
+ * `'strict-dynamic'` that changes what host lists even mean, a CSP with no script directive at
+ * all — all of them pass. A deployed smoke decides whether an app's `scripts/deploy.ts` rolls
+ * back; a false red there discards good work over a CSP grammar corner, so the only thing that
+ * fails here is a script with NO source expression that could admit it.
+ */
+
+/** An absolute script URL found in the HTML, with the origin already resolved. */
+export interface InjectedScript {
+	/** Exactly as it appeared in the markup, for the failure message. */
+	src: string;
+	/** `https://static.cloudflareinsights.com`, resolved against the page's own URL. */
+	origin: string;
+}
+
+/**
+ * Every `<script src=…>` in `html` whose origin is NOT `pageUrl`'s.
+ *
+ * Inline scripts are ignored: they are the page's own (most shells here ship one, a pre-paint
+ * colour-scheme script) and a CSP that refuses them is a different finding from this one.
+ * `data:` and `blob:` are ignored for the same reason — neither is a host anything could have
+ * injected.
+ */
+export function foreignScriptSources(html: string, pageUrl: string): InjectedScript[] {
+	const page = new URL(pageUrl);
+	const found: InjectedScript[] = [];
+	const seen = new Set<string>();
+	const tag = /<script\b[^>]*?\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi;
+	for (const match of html.matchAll(tag)) {
+		const raw = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+		if (!raw) continue;
+		let origin: string;
+		try {
+			const url = new URL(raw, page);
+			if (url.protocol !== "http:" && url.protocol !== "https:") continue;
+			origin = url.origin;
+		} catch {
+			continue; // not a URL this check can reason about — see the conservative note
+		}
+		if (origin === page.origin) continue;
+		if (seen.has(origin + raw)) continue;
+		seen.add(origin + raw);
+		found.push({ src: raw, origin });
+	}
+	return found;
+}
+
+/**
+ * Which of `scripts` the `content-security-policy` header would refuse.
+ *
+ * `null`/absent/empty header means no policy, which refuses nothing. The directive consulted
+ * is `script-src-elem`, then `script-src`, then `default-src` — the browser's own fallback
+ * order for a `<script src>` element.
+ */
+export function scriptsRefusedByCsp(
+	csp: string | null | undefined,
+	scripts: InjectedScript[],
+	pageUrl: string,
+): InjectedScript[] {
+	if (!csp?.trim() || scripts.length === 0) return [];
+	const directives = new Map<string, string[]>();
+	for (const part of csp.split(";")) {
+		const tokens = part.trim().split(/\s+/).filter(Boolean);
+		const name = tokens.shift()?.toLowerCase();
+		if (name && !directives.has(name)) directives.set(name, tokens);
+	}
+	const sources =
+		directives.get("script-src-elem") ??
+		directives.get("script-src") ??
+		directives.get("default-src");
+	if (!sources) return [];
+	// `'strict-dynamic'` makes host allowlists inert in ways that depend on how the script was
+	// reached. Not decidable from the markup alone, so it is permitted — see the header.
+	if (sources.some((s) => s.toLowerCase() === "'strict-dynamic'")) return [];
+	const self = new URL(pageUrl).origin;
+	return scripts.filter(
+		(script) => !sources.some((source) => sourceAdmits(source, script.origin, self)),
+	);
+}
+
+/** Does one CSP source expression admit `origin`? Unparseable ⇒ yes, deliberately. */
+function sourceAdmits(source: string, origin: string, self: string): boolean {
+	const value = source.trim();
+	if (!value) return false;
+	if (value === "*") return true;
+	if (value.startsWith("'")) {
+		const keyword = value.toLowerCase();
+		if (keyword === "'self'") return origin === self;
+		// `'none'`, `'unsafe-inline'`, `'nonce-…'`, `'sha256-…'`, `'report-sample'`: none of
+		// them admits a host, and `'none'` in particular must not.
+		return false;
+	}
+	let target: URL;
+	try {
+		target = new URL(origin);
+	} catch {
+		return true;
+	}
+	// A bare scheme source — `https:`, `data:`.
+	if (/^[a-z][a-z0-9+.-]*:$/i.test(value)) return value.toLowerCase() === target.protocol;
+
+	const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.exec(value);
+	let rest = value;
+	if (withScheme) {
+		if (withScheme[0].toLowerCase() !== `${target.protocol}//`) return false;
+		rest = value.slice(withScheme[0].length);
+	}
+	// Port and path narrow a source; ignoring them can only ever ADMIT more, which is the
+	// direction this file errs in.
+	const host = rest.split("/")[0]?.split(":")[0]?.toLowerCase() ?? "";
+	if (!host) return true;
+	if (host === "*") return true;
+	if (host.startsWith("*.")) return target.hostname.toLowerCase().endsWith(host.slice(1));
+	return target.hostname.toLowerCase() === host;
+}

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

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import {
+	WEB_ANALYTICS_BEACON_ORIGIN,
+	WEB_ANALYTICS_BEACON_SRC,
+	WEB_ANALYTICS_SITE_TAG,
+	WEB_ANALYTICS_SITE_TOKEN,
+	WEB_ANALYTICS_TAG,
+	htmlCarriesWebAnalytics,
+	webAnalyticsTag,
+} from "./webAnalytics";
+
+/**
+ * 🔴 The snippet, as Cloudflare's own `GET /accounts/<acct>/rum/site_info/list` returned it on
+ * 2026-09-18 for `cursedalchemy.com`, unescaped. Pinning it byte-for-byte is the point: this
+ * is the thing a shell pastes, and the day it drifts from the vendor's text is a day nobody
+ * would otherwise notice until a dashboard stopped filling.
+ */
+const FROM_CLOUDFLARE =
+	`<!-- Cloudflare Web Analytics --><script type='module' src='https://static.cloudflareinsights.com/beacon.min.js' ` +
+	`data-cf-beacon='{"token": "bd88d63678b64bc89f9702f48846bc88"}'></script><!-- End Cloudflare Web Analytics -->`;
+
+describe("the fleet's beacon", () => {
+	test("is exactly the snippet Cloudflare hands out for this site", () => {
+		expect(WEB_ANALYTICS_TAG).toBe(FROM_CLOUDFLARE);
+	});
+
+	test("carries the site TOKEN, never the site TAG", () => {
+		// Both are 32 hex characters and swapping them errors nowhere — the page loads, the
+		// beacon loads, and the pageview is recorded against nothing.
+		expect(WEB_ANALYTICS_TAG).toContain(WEB_ANALYTICS_SITE_TOKEN);
+		expect(WEB_ANALYTICS_TAG).not.toContain(WEB_ANALYTICS_SITE_TAG);
+		expect(WEB_ANALYTICS_SITE_TAG).not.toBe(WEB_ANALYTICS_SITE_TOKEN);
+	});
+
+	test("the src is under the origin a CSP would have to admit", () => {
+		expect(WEB_ANALYTICS_BEACON_SRC.startsWith(`${WEB_ANALYTICS_BEACON_ORIGIN}/`)).toBe(true);
+		expect(new URL(WEB_ANALYTICS_BEACON_SRC).origin).toBe(WEB_ANALYTICS_BEACON_ORIGIN);
+	});
+
+	test("another site's token produces that site's tag and nothing else changes", () => {
+		const other = webAnalyticsTag("0".repeat(32));
+		expect(other).toContain(WEB_ANALYTICS_BEACON_SRC);
+		expect(other).not.toContain(WEB_ANALYTICS_SITE_TOKEN);
+	});
+});
+
+describe("htmlCarriesWebAnalytics", () => {
+	test("true for the tag as authored, and for a re-wrapped copy of it", () => {
+		expect(htmlCarriesWebAnalytics(`<head>${WEB_ANALYTICS_TAG}</head>`)).toBe(true);
+		// A formatter is allowed to break the attributes across lines; the check must survive it.
+		const rewrapped =
+			`<script\n\ttype="module"\n\tsrc="${WEB_ANALYTICS_BEACON_SRC}"\n` +
+			`\tdata-cf-beacon='{"token": "${WEB_ANALYTICS_SITE_TOKEN}"}'\n></script>`;
+		expect(htmlCarriesWebAnalytics(rewrapped)).toBe(true);
+	});
+
+	test("false for a shell with no beacon at all", () => {
+		expect(htmlCarriesWebAnalytics("<head><title>Vault</title></head>")).toBe(false);
+	});
+
+	test("false when the src is right but the token is somebody else's", () => {
+		expect(htmlCarriesWebAnalytics(webAnalyticsTag("0".repeat(32)))).toBe(false);
+	});
+
+	test("false when the token is right but the src is not the beacon", () => {
+		expect(htmlCarriesWebAnalytics(`<!-- ${WEB_ANALYTICS_SITE_TOKEN} -->`)).toBe(false);
+	});
+});

package/src/server/analytics/webAnalytics.ts

@@ -0,0 +1,92 @@
+/**
+ * Cloudflare Web Analytics — ONE definition of the beacon, for every app on the fleet.
+ *
+ * ## 🔴 Why this is here and not in each app's `index.html` alone
+ *
+ * Until 2026-09-18 the zone carried **Automatic Setup**: Cloudflare rewrote every HTML
+ * response leaving `cursedalchemy.com` and appended the beacon tag. Nothing in any repo
+ * asked for it, nothing in any repo could see it locally, and it arrived on pages that
+ * deliberately refuse third-party script — including the master-lock wall, where a master
+ * password is typed. The owner read a console during an outage on 2026-09-17 and the FIRST
+ * line was that tag being refused; it broke nothing and cost an agent the first minutes of
+ * the incident.
+ *
+ * His decision, 2026-09-18, in his words: *"do your recommendation with option c but not on
+ * the wall. If we can stop the console error that would be good since we are purposely
+ * blocking on that page and it makes it look like there is a mistake when it shows."* — and,
+ * on why the wall's CSP may not simply be loosened: *"I don't want to trust cloudflare with
+ * master password data that is typed in."*
+ *
+ * So the install method moves from automatic to MANUAL. Same site, same dashboard, same
+ * data; the difference is that the fleet now decides *which pages* carry it. Public shells
+ * do. {@link "../master-lock/guard".MASTER_LOCK_CSP the wall} does not — and under manual
+ * setup it is not injected into at all, so there is no refused script and no console line.
+ *
+ * ## 🔴 `token` is the site TOKEN, not the site TAG
+ *
+ * They are both 32 hex characters and they are not interchangeable. `site_tag`
+ * ({@link WEB_ANALYTICS_SITE_TAG}) is the id the RUM API addresses the site by;
+ * `site_token` ({@link WEB_ANALYTICS_SITE_TOKEN}) is what goes in `data-cf-beacon`. Putting
+ * the tag in the snippet does not error anywhere — the page loads, the beacon loads, and the
+ * data goes nowhere. Measured 2026-09-18 against
+ * `GET /accounts/<acct>/rum/site_info/list`, which returns both fields **and** the ready-made
+ * `snippet`; {@link WEB_ANALYTICS_TAG} is that snippet byte-for-byte, and the token in it is
+ * the same one the edge was injecting.
+ *
+ * Neither value is a secret: the token is served to every visitor inside every page's HTML,
+ * which is the whole mechanism. It is an identifier, not a credential.
+ */
+
+/** The host the beacon is fetched from — the origin a CSP would have to admit. */
+export const WEB_ANALYTICS_BEACON_ORIGIN = "https://static.cloudflareinsights.com";
+
+/** The beacon itself. Manual setup serves the unversioned path; the edge served a pinned one. */
+export const WEB_ANALYTICS_BEACON_SRC = `${WEB_ANALYTICS_BEACON_ORIGIN}/beacon.min.js`;
+
+/**
+ * The `cursedalchemy.com` site's id in the RUM API. **Not** what goes in the tag — see the
+ * module note. Kept beside the token so the next reader cannot pick the wrong one by accident.
+ */
+export const WEB_ANALYTICS_SITE_TAG = "d1bea8562544421fbd2db5f11b74d1cc";
+
+/** The `cursedalchemy.com` site's `data-cf-beacon` token. This is what the tag carries. */
+export const WEB_ANALYTICS_SITE_TOKEN = "bd88d63678b64bc89f9702f48846bc88";
+
+/**
+ * The snippet, exactly as Cloudflare's own `site_info` endpoint spells it.
+ *
+ * 🔴 The single-quoted attributes and the space after `"token":` are Cloudflare's, not a
+ * style choice, and they are kept because this string is COMPARED against what an app's
+ * shell contains. `data-cf-beacon`'s value is JSON containing double quotes, so the attribute
+ * quoting cannot be flipped without escaping; leaving it identical to the vendor's text means
+ * a future reader can diff it against the dashboard in one glance.
+ *
+ * `type='module'` rather than `defer`: that is what the endpoint returns today and what the
+ * edge was injecting, so switching install methods changes nothing about how the page loads.
+ */
+export function webAnalyticsTag(token: string = WEB_ANALYTICS_SITE_TOKEN): string {
+	return (
+		"<!-- Cloudflare Web Analytics -->" +
+		`<script type='module' src='${WEB_ANALYTICS_BEACON_SRC}' ` +
+		`data-cf-beacon='{"token": "${token}"}'></script>` +
+		"<!-- End Cloudflare Web Analytics -->"
+	);
+}
+
+/** The fleet's tag, for the one site this generation serves. */
+export const WEB_ANALYTICS_TAG = webAnalyticsTag();
+
+/**
+ * Does `html` carry the beacon for this site?
+ *
+ * Deliberately NOT a substring test against {@link WEB_ANALYTICS_TAG}: a shell is authored by
+ * hand and a formatter is allowed to re-wrap the tag across lines or re-order its attributes.
+ * What must be true is that the beacon's source is there AND that it is carrying the right
+ * token — the two halves that decide whether a pageview is recorded at all.
+ */
+export function htmlCarriesWebAnalytics(
+	html: string,
+	token: string = WEB_ANALYTICS_SITE_TOKEN,
+): boolean {
+	return html.includes(WEB_ANALYTICS_BEACON_SRC) && html.includes(token);
+}

package/src/server/d1/index.ts

@@ -25,7 +25,13 @@ export {
 	type LocalBackupOpts,
 	type TimeTravelOpts,
 } from './backup';
-export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+// 🔴 `./kysely` is deliberately NOT re-exported here — import it from
+// `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
+// `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it
+// made `import 'cursedbelt-server/d1'` throw `Cannot find package 'kysely'` for every app
+// that does not use the query builder — which per `../db/kysely.ts`'s own header is most
+// of them, since business tables stay on raw statements. Measured 2026-09-18 against the
+// published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';