fix: opt out of edge html transformation

Author: bhdicaire

defaults/public/_headers

@@ -9,10 +9,10 @@
   Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; font-src 'self'; img-src 'self' data:; connect-src 'self' https://api.github.com; base-uri 'self'; form-action 'self'; frame-ancestors 'none'
 
 /
-  Cache-Control: no-store
+  Cache-Control: no-store, no-transform
 
 /index.html
-  Cache-Control: no-store
+  Cache-Control: no-store, no-transform
 
 /v8s-style.css
   Cache-Control: no-store
@@ -26,11 +26,11 @@
   Content-Type: text/markdown; charset=utf-8
 
 /lookup/*
-  Cache-Control: no-store
+  Cache-Control: no-store, no-transform
   X-Robots-Tag: noindex, nofollow
 
 /:lang/_stats/*
-  Cache-Control: no-store
+  Cache-Control: no-store, no-transform
   X-Robots-Tag: noindex, nofollow
   X-Content-Type-Options: nosniff
 

defaults/public/llms-full.txt

@@ -52,11 +52,13 @@ The localized `_stats` dashboard exposes routing inventory and should be protect
 
 The default policy rejects risky destinations such as credentialed URLs, non-HTTP(S) protocols, private IP ranges, known shortener chains, phishing lures, and high-risk executable downloads. Instance owners can replace that source policy with `custom/v8s-policies.json` and must not use the redirect engine for phishing, malware, undisclosed tracking, or other harmful activity.
 
+Public HTML responses use strict CSP and `Cache-Control: no-store, no-transform` so Cloudflare edge features do not rewrite or inject JavaScript into repository-owned pages. Keep challenge-style or page-rewriting dashboard controls disabled for public redirect, lookup, and status pages unless the instance deliberately accepts Cloudflare-owned script injection.
+
 ## Instance Maintenance
 
-Product defaults live in `defaults/`. Instance-owned files live in `custom/` and are not overwritten automatically during updates. The build copies defaults first, overlays `custom/public` only when copied public files exist, and then generates runtime files.
+Product defaults live in `defaults/`. Instance-owned files live in `custom/` and are not overwritten automatically during updates. The build copies defaults first, overlays `custom/public` only when copied public files exist, and then generates runtime files. Product-managed public runtime assets use `v8s-` filenames and should normally stay in `defaults/public/`; custom copies under `custom/public/` shadow the release asset.
 
-Use `npm run doctor` to detect stale copied public assets, stale copied product pages, unsupported copied language folders, stale branding, and missing shared head assets. Use `./scripts/v8s-fix --assets`, `--head-assets`, `--product-pages`, `--languages`, `--branding`, or `--all` to apply explicit maintenance fixes to copied public files.
+Use `npm run doctor` to detect managed `v8s-` asset shadows, stale copied product pages, unsupported copied language folders, stale branding, and missing shared head assets. Use `./scripts/v8s-fix --assets`, `--head-assets`, `--product-pages`, `--languages`, `--branding`, or `--all` to apply explicit maintenance fixes to copied public files. The `--assets` fix removes `custom/public/v8s-*` shadows so the build uses the release assets from `defaults/public/`.
 
 ## Useful Files
 

docs/adr/0018-keep-managed-public-assets-in-defaults.md

@@ -0,0 +1,40 @@
+# 0018. Keep managed public assets in defaults
+
+Date: 2026-06-15
+
+Status: Accepted
+
+## Context
+
+The build publishes public files by copying `defaults/public/` first and then overlaying `custom/public/`. That makes
+custom HTML pages and instance-owned assets easy to maintain without editing upstream defaults.
+
+Product-owned runtime assets, however, also live in the public surface. Files such as `v8s-style.css`, `v8s-script.js`,
+`v8s-lookup.js`, `v8s-stats.js`, `v8s-status.css`, `v8s-tests.js`, and `v8s-theme.js` are part of the release package.
+Copying them into `custom/public/` turns them into local shadows. Those shadows can keep serving stale product
+JavaScript or CSS after an upgrade, and they make routine upgrades look like instance customization work.
+
+## Decision
+
+Product-managed public runtime assets with `v8s-` filenames stay in `defaults/public/`. Instance repositories should not
+copy them into `custom/public/` as part of normal maintenance. The build already includes the default asset from
+`defaults/public/` when no custom shadow exists.
+
+`custom/public/` remains the right place for instance-owned HTML, CSS, JavaScript, fonts, images, manifests, and page
+replacements. Instance-specific assets should use instance-owned filenames instead of `v8s-` product names.
+
+When `npm run doctor` sees `custom/public/v8s-*`, it treats the file as a managed asset shadow. The recommended
+`./scripts/v8s-fix --assets` action removes the shadow so the next build uses the product asset from `defaults/public/`.
+
+If an operator deliberately forks a `v8s-` runtime asset, that file becomes a maintained local fork. The operator should
+document the exception in `custom/v8s-custom-overrides.json` with a narrow ignore and accept that upgrades will not
+automatically update the fork.
+
+## Consequences
+
+- Product CSS and JavaScript fixes reach existing instances during upgrade without copying files into `custom/public/`
+- `custom/public/` stays focused on instance-owned pages and assets
+- `v8s-fix --assets` removes stale managed shadows instead of syncing copies from defaults
+- Deliberate product-asset forks remain possible, but they are explicit local maintenance decisions
+- Custom pages can still reference same-host instance CSS, JavaScript, fonts, images, and manifests under non-product
+  filenames

docs/adr/0019-opt-out-of-edge-html-transformation.md

@@ -0,0 +1,43 @@
+# 0019. Opt out of edge HTML transformation
+
+Date: 2026-06-15
+
+Status: Accepted
+
+## Context
+
+vanityURLs ships strict Content Security Policy headers for product HTML. The default CSP blocks inline scripts and
+styles so the generated redirector pages remain deterministic and easy to audit.
+
+Some Cloudflare dashboard features can rewrite or inject content into HTML responses after the Worker or static asset
+policy has produced the page. JavaScript Detections, Bot Fight Mode, Managed Challenge, Zaraz, Rocket Loader, Snippets,
+and similar features can add scripts or rewrite markup at the edge. That creates a mismatch between repository-owned
+HTML/CSP and the final response observed by browsers. In strict-CSP instances, the result is often a browser console
+error for an injected inline script.
+
+Cloudflare JavaScript Detections documents its injected script path under `/cdn-cgi/challenge-platform/` and notes that
+`Cache-Control: no-transform` prevents that injection on responses where JavaScript Detections would otherwise run.
+
+## Decision
+
+vanityURLs HTML responses opt out of intermediary transformation. The Worker appends `no-transform` to the
+`Cache-Control` header for HTML responses, and the static `_headers` fallback uses
+`Cache-Control: no-store, no-transform` on HTML routes.
+
+The operator recommendation remains to keep challenge-style or page-rewriting Cloudflare features disabled for public
+redirect, lookup, and status HTML unless the instance intentionally accepts Cloudflare-owned script injection.
+
+Do not weaken the default CSP with `unsafe-inline` or Cloudflare-generated hashes just to support dashboard-injected
+JavaScript. If an operator wants JavaScript Detections on a separate application surface, that surface should carry its
+own policy instead of changing the redirector baseline.
+
+## Consequences
+
+- Public HTML remains closer to the repository-built artifact that operators review and deploy
+- Cloudflare JavaScript Detections should not inject its challenge-platform script into vanityURLs HTML responses that
+  honor `no-transform`
+- Strict CSP can remain strict without inline script allowances
+- Operators can still enable Cloudflare blocking, rate limiting, Browser Integrity Check, Access, managed AI bot
+  controls, and WAF rules that do not rewrite public HTML
+- Challenge-based controls may still be useful on separate apps or protected admin surfaces, but they are not the
+  vanityURLs public HTML baseline

scripts/workers/worker.mjs

@@ -75,6 +75,10 @@ async function withSecurityHeaders(response, context) {
     headers.set("content-security-policy", CUSTOM_HTML_CONTENT_SECURITY_POLICY);
   }
 
+  if (isHtmlResponse(response)) {
+    appendCacheControlDirective(headers, "no-transform");
+  }
+
   return new Response(response.body, {
     status: response.status,
     statusText: response.statusText,
@@ -94,6 +98,20 @@ function isHtmlResponse(response) {
   return contentType.toLowerCase().startsWith("text/html");
 }
 
+function appendCacheControlDirective(headers, directive) {
+  const current = headers.get("cache-control") || "";
+  const directives = current
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  if (!directives.some((entry) => entry.toLowerCase() === directive.toLowerCase())) {
+    directives.push(directive);
+  }
+
+  if (directives.length) headers.set("cache-control", directives.join(", "));
+}
+
 async function loadCustomAssets(request, env) {
   customAssetsPromise ||= (async () => {
     const response = await fetchAsset(request, env, "/v8s-custom-assets.json");

scripts/workers/worker.test.mjs

@@ -583,6 +583,15 @@ await run("applies security headers across response classes and preserves explic
     assert(response.headers.get("content-security-policy"), `${name} csp`);
   }
 
+  const html = await worker.fetch(request("/"), env(), mockCtx());
+  assert(html.headers.get("cache-control").includes("no-transform"), "html opts out of edge transformation");
+
+  const css = await worker.fetch(request("/v8s-style.css"), env(), mockCtx());
+  assert(
+    !String(css.headers.get("cache-control") || "").includes("no-transform"),
+    "non-html cache control is unchanged"
+  );
+
   const custom = await worker.fetch(request("/custom-header.html"), env(), mockCtx());
   assert(custom.headers.get("content-security-policy") === "default-src 'none'", "explicit csp preserved");
   assert(custom.headers.get("x-frame-options") === "DENY", "other security headers still added");