Skip to content

0040: Website stack, analytics, security headers and the launch gate

  • Status: accepted (the maintainer confirmed the analytics decision on 2026-10-19)
  • Date: 2026-10-17
  • Amended by: 0050 (the launch gate, a waitlist and a preview deploy) and 0065 (a waitlist form, form-action 'self' and one Pages Function)

Context

The add-marketing-site change builds the public site at vaultfold.app (ADR 0027): landing pages for consumers, families and teams, a documentation section for readers who are not in the repository, and comparison pages. The site must not make a claim the product cannot yet back, must not track visitors, and must not ship a weaker security posture than the product it describes. The reasoning for each point below is in openspec/changes/add-marketing-site/design.md; the operating procedure is in web/README.md. The maintainer confirmed the analytics decision below on 2026-10-19; the rest was settled while building groups 1 to 8. (The number is 0040: 0022 was already taken by the interactive prompts ADR.)

Decision

  • Astro plus Starlight, static output. The site is an Astro project in web/site using the Starlight documentation theme, built to static files. Marketing pages ship no JavaScript. The workspace is pnpm, runs in a pinned container (Dockerfile.web) and every dependency is added through the package manager. Account, billing and team-management interfaces are not part of this site; they belong to the hosted service (ADR 0015).

  • Repository docs are rendered, not copied. The ADRs and the threat model are read from docs/adr/ and docs/threat-model.md at build time by content loaders (web/site/src/loaders/repo-docs.ts), and chosen README sections are pulled in with a ReadmeSection component that extracts one level-2 section by exact heading. A README edit that removes a heading the site uses fails the build. The no copies check fails if anything under web/ contains an ADR title line or the threat model's title line, so a copy cannot silently drift from the source.

  • The CLI reference is committed and generated from the binary. make web-cli-ref builds vaultfold, walks its --help output and writes one page per command under web/site/src/content/docs/docs/reference/cli/. The pages are committed, so a docs build needs no Go toolchain and a CLI help change shows up as a diff in review. Two checks pin them against drift: web-check regenerates the pages and compares them byte for byte, and a Go test (TestWebCLIReferenceMatchesHelp, part of make check) compares each page with the command's help, so a CLI PR that never touches web/ still fails when it changes help text.

  • No analytics beyond aggregate edge counts, and no cookies. The pages carry no analytics script, beacon or identifier, and set no cookie. The only measurement is the aggregate request analytics that Cloudflare records at the edge for every proxied zone (requests, bandwidth, top paths, status codes, countries). Considered and rejected: a privacy-focused analytics script (breaks the zero-JavaScript budget, needs a CSP exception and is telemetry by another name) and server-side log analysis through a worker (more infrastructure and a per-visitor record we would have to justify keeping). Download counts will come from the release host. The privacy page therefore says exactly this: the site sets no cookies, loads no analytics script and does no per-visitor tracking, and the host keeps aggregate request counts per page. It does not claim the host measures nothing. Any change needs an amendment to this record. The maintainer confirmed this decision on 2026-10-19.

  • A strict Content-Security-Policy generated from the build. web/site/scripts/headers.ts writes dist/_headers after the build, and an independent check re-parses dist/ and fails on any mismatch. The policy starts from default-src 'none', allows only 'self' (plus data: for images) and no other origin in any directive, and never allows 'unsafe-inline' or 'unsafe-eval' for scripts. The exceptions actually present in the built dist/_headers are:

    • Marketing pages (everything outside /docs/): none. script-src 'self', style-src 'self', no style-src-attr, no script hash. An executable inline script on a marketing page makes the generator throw and the header and budget checks fail.
    • Documentation pages (/docs/*, a separate block that detaches the marketing policy first, because Cloudflare joins same-named headers and two joined policies would both be enforced): 'wasm-unsafe-eval' in script-src because Pagefind search loads WebAssembly; nine sha256 hashes of Starlight's inline scripts (all nine are scripts); and style-src-attr 'unsafe-inline' because Starlight sets style attributes on icons and layout elements, which cannot be hashed without 'unsafe-hashes' and cannot execute script.

    Every response also carries HSTS (max-age=63072000; includeSubDomains; preload), nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY, Cross-Origin-Opener-Policy: same-origin and a restrictive Permissions-Policy; the project's pages.dev alias adds X-Robots-Tag: noindex. Preload needs no submission because the whole .app top-level domain is preloaded (ADR 0027). If search ever has to go, removing it removes the 'wasm-unsafe-eval' exception.

  • A claims registry and a launch gate. Every product claim, price, platform, store, trust signal and competitor name on a marketing page is an entry in web/claims.yaml and appears on the page only through <Claim id="...">. Each entry lists the sources that make it true, and the source kinds are change (an OpenSpec change that must be archived), baseline (a requirement in openspec/specs/ whose implementing change is archived), adr (an ADR with Status accepted or amended), evidence (a repository path that must exist) and noChangeYet (a known gap that no change covers). A competitor is a separate entry kind with its own source URL and a checked date that must be no more than 90 days old. The term rule: each entry lists the terms it owns, and a registered term, a currency amount, a percentage off, a certification or audit name, a platform or store name or a competitor name in the text of a marketing page outside an element that carries a claim listing it fails web-check. The launch gate (make web-launch-status) prints every unsatisfied source and exits non-zero while any remain, including any noChangeYet source and any bracketed PENDING marker in a built page. Mid-build gaps are allowed in the copy and refused at deploy time. There is no override: no flag, variable or target deploys while the gate fails, and there is no preview deploy target, because a Pages preview URL is public and a public copy of the unfinished site is what the maintainer ruled out. Review happens on make web-dev.

  • Direct-upload deploy to Cloudflare Pages. make web-deploy runs web/scripts/deploy.sh on the maintainer's machine, with the Cloudflare token and account id in the environment and never committed. In order, and stopping at the first failure: build, the launch gate, a clean tree with HEAD equal to origin/main, the two variables, make web-check, then wrangler pages deploy web/site/dist --project-name vaultfold --branch main, then make web-verify-live. The gate runs after the build only because it needs the built pages; nothing is checked for upload or uploaded before it passes. Git integration on the Pages project is disabled, matching the local-gates convention. Other domains the project holds redirect to vaultfold.app through a Cloudflare Bulk Redirect rule, and zone features that set cookies stay off, which web-verify-live catches.

Consequences

  • The site cannot go live until every claim is true; the cost is that archiving a change, accepting an ADR or finishing a gap is now on the launch path, and the human items are tracked in docs/STATUS.md.
  • We cannot measure conversion or referrers beyond aggregate edge counts. That is accepted.
  • A Starlight upgrade that adds or changes an inline script changes the docs hashes; the generator recomputes them on every build and the check catches a stale one.
  • Cloudflare's behavior for the detach-then-set CSP on /docs/* has been verified against the documented semantics and the pages-shared code, not yet against a live Pages deployment. The first deploy must confirm with curl -I that docs pages carry exactly one policy; this is a launch item in docs/STATUS.md.
  • make -i web-deploy exits 0 from the outer make even though the script refused, because -i ignores the inner failure. Run the target plainly. The Makefile's temporary wrangler shim is removed by a shell trap that runs under /bin/sh, so a hard interruption can leave its temporary directory behind; it holds no secret.
  • Pagefind's 'wasm-unsafe-eval' and Starlight's style-src-attr exceptions apply to documentation pages (and, since the early-access amendment below, to Pagefind's own files under /pagefind/) and are asserted by the header check, so a stale exception is also a failure.

Amendment: early-access launch (ADR 0050, launch-site-mvp)

ADR 0050 amends the launch gate; everything else here (analytics, headers, the Content-Security-Policy, accessibility, the budget) is unchanged.

  • A registry entry may have status: roadmap. It has no sources, a waitingOn note and a text that holds no price, percentage off, certification or audit name, or date. <Claim> renders it with a visible "Coming soon:" label, the term rule applies to it as to any claim, and the launch gate treats it as satisfied but fails when a built page outside /docs/ shows one without the words "coming soon". make web-launch-status lists the roadmap entries after any blockers; the list never changes the exit status. The gate still has no override.
  • The statements above that the site may carry no waitlist and that there is no preview deploy are superseded. The home and download pages carry a mailto: waitlist link to hello@vaultfold.app (no form, no input, no script) and a preview deploy behind the same gate is allowed (ADR 0050; the target is added by the deploy-preparation group).
  • The preview deploy is make web-deploy-preview, which runs web/scripts/deploy-preview.sh. It follows the production deploy's order and has the same launch gate with no override, but it requires only a clean tree (no origin/main requirement) and uploads with the literal branch preview and --commit-hash set to HEAD, so it can never replace the production deployment. The result is verified with make web-verify-live URL=https://preview.vaultfold.pages.dev, and the script prints the X-Robots-Tag the alias serves as an observation.

Pagefind runs its WebAssembly in a Web Worker, and a worker is governed by the policy of its own script response, not the page's. The strict marketing policy that /* gave /pagefind/* therefore blocked instantiation. When dist/pagefind exists the generator writes a /pagefind/* block after /docs/*: it detaches the marketing policy and sets exactly the documentation policy (the same string as /docs/*). When _headers has that block, make web-verify-live requests /pagefind/pagefind-worker.js and checks it carries what the block assigns.

Preview verification (2026-11-01, launch-site-mvp tasks 2.5 and 2.6)

  • wrangler 4.151.0 pages deploy works on the classic direct-upload project: make web-deploy-preview uploaded 359 files to the preview alias and make web-verify-live passed, so no move to Workers static assets is needed.
  • Every response on the preview carries exactly one Content-Security-Policy. The two /docs/ pages checked carry 'wasm-unsafe-eval' and style-src-attr 'unsafe-inline'; /, /security/, /download/ and /privacy/ carry the strict policy, identical to headers.ts output. The preview sends x-robots-tag: noindex.
  • Gap found: Pagefind search on /docs/ fails under the policy. Its WebAssembly is instantiated in a Web Worker, whose policy comes from the worker script's own response, and /pagefind/* is served under the strict /* policy. That was fixed by the /pagefind/* block described above (#225). Details are in the change's design.md "Results".

Preview verification, second run (2026-11-14, task 2.6)

  • make web-deploy-preview from staging at de1dc0c: wrangler 4.151.0, 391 files, make web-verify-live passed on 170 pages and the redirects.
  • One Content-Security-Policy on every URL checked. /docs/ pages and /pagefind/pagefind-worker.js and /pagefind/pagefind.js carry 'wasm-unsafe-eval'; /, /security/, /download/ and /privacy/ do not. No Set-Cookie anywhere.
  • Pagefind search works in the pinned Playwright image: 78 results for "agent" on /docs/, and no console message on /, /security/ or /docs/.

Live (2026-11-15, launch-site-mvp tasks 3.3 and 3.4)

  • The site is live at https://vaultfold.app: make web-deploy from origin/main at 7effdbe, wrangler 4.151.0, 391 files, and its make web-verify-live step passed on 170 pages and the redirects.
  • One Content-Security-Policy on every URL checked on the apex. /, /security/, /download/ and /pricing/ carry the strict policy; /docs/, /docs/adr/, /docs/security/threat-model/ and /docs/reference/cli/add/ carry 'wasm-unsafe-eval' and style-src-attr 'unsafe-inline'. No Set-Cookie anywhere and no x-robots-tag on the apex. www.vaultfold.app does not resolve (apex only, Ben's decision).
  • Three Cloudflare edge features were rewriting the served HTML after the first deploy, and each is now off: Email Address Obfuscation (it replaced the waitlist mailto: link with a /cdn-cgi/l/email-protection link and added a script; off on the dashboard), JavaScript Detections (an inline script on every page loading a /cdn-cgi/challenge-platform/ script; on in the zone although Bot Fight Mode was off, with no toggle on the free-plan dashboard, so turned off through the API by setting enable_js to false on the zone's bot_management settings) and the Web Analytics beacon from static.cloudflareinsights.com (injected only for requests with a browser User-Agent; the site was disabled in the account-level Web Analytics list). The policy blocked both injected scripts (the beacon loaded nothing and collected nothing), but each cost a console message per page, and the waitlist link was not the one the build wrote.
  • After that, a browser check in the pinned Playwright image of /, /download/, /pricing/, /security/ and /docs/ at two viewport sizes showed no console message, no failed request, no /cdn-cgi/ request, the mailto:hello@vaultfold.app waitlist link intact and docs search returning 36 results for "sync".
  • Lesson: a feature of the edge can alter the pages it serves without the build, the header generator or make web-verify-live noticing, because those compare headers and cookies and never read the HTML a browser receives; make web-verify-live passed throughout, and curl's default User-Agent did not even receive the beacon. The zone settings that must stay off are Email Address Obfuscation, JavaScript Detections, Web Analytics injection, Rocket Loader and Bot Fight Mode, and a deploy is checked with a browser User-Agent afterwards (web/README.md, "Deploy at launch"). Ticket 01M7FMFFFRJVE2CE1D0EJ04SNG extends verify-live to fail on any script, /cdn-cgi/ or cloudflareinsights reference the build did not emit and on a changed mailto: target. Details are in the change's design.md "Results".

Amendment: the waitlist form (ADR 0065, waitlist-form)

ADR 0065 amends three points here; analytics, cookies, the rest of the Content-Security-Policy, accessibility and the budget are unchanged.

  • The site may carry one form, the waitlist form on the home and download pages (and the button form of /waitlist/confirm/), posting to its own origin. Marketing pages still ship no JavaScript.
  • form-action is 'self' in both policies instead of 'none'.
  • The only request-time code is one Pages Function serving /api/waitlist and /api/waitlist/confirm, routed on those paths only by _routes.json. It sets the /* headers on its own responses from functions/_generated/headers.json, which the header generator writes and the header check compares with dist/_headers. The deploy scripts run wrangler in web/site so that functions/ is compiled, and refuse to upload while the function's secrets are missing.