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/siteusing 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/anddocs/threat-model.mdat build time by content loaders (web/site/src/loaders/repo-docs.ts), and chosen README sections are pulled in with aReadmeSectioncomponent that extracts one level-2 section by exact heading. A README edit that removes a heading the site uses fails the build. Theno copiescheck fails if anything underweb/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-refbuildsvaultfold, walks its--helpoutput and writes one page per command underweb/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-checkregenerates the pages and compares them byte for byte, and a Go test (TestWebCLIReferenceMatchesHelp, part ofmake check) compares each page with the command's help, so a CLI PR that never touchesweb/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.tswritesdist/_headersafter the build, and an independent check re-parsesdist/and fails on any mismatch. The policy starts fromdefault-src 'none', allows only'self'(plusdata: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 builtdist/_headersare:- Marketing pages (everything outside
/docs/): none.script-src 'self',style-src 'self', nostyle-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'inscript-srcbecause Pagefind search loads WebAssembly; ninesha256hashes of Starlight's inline scripts (all nine are scripts); andstyle-src-attr 'unsafe-inline'because Starlight setsstyleattributes 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-originand a restrictivePermissions-Policy; the project'spages.devalias addsX-Robots-Tag: noindex. Preload needs no submission because the whole.apptop-level domain is preloaded (ADR 0027). If search ever has to go, removing it removes the'wasm-unsafe-eval'exception. - Marketing pages (everything outside
-
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.yamland appears on the page only through<Claim id="...">. Each entry lists the sources that make it true, and the source kinds arechange(an OpenSpec change that must be archived),baseline(a requirement inopenspec/specs/whose implementing change is archived),adr(an ADR with Status accepted or amended),evidence(a repository path that must exist) andnoChangeYet(a known gap that no change covers). A competitor is a separate entry kind with its own source URL and acheckeddate 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 failsweb-check. The launch gate (make web-launch-status) prints every unsatisfied source and exits non-zero while any remain, including anynoChangeYetsource 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 onmake web-dev. -
Direct-upload deploy to Cloudflare Pages.
make web-deployrunsweb/scripts/deploy.shon 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 toorigin/main, the two variables,make web-check, thenwrangler pages deploy web/site/dist --project-name vaultfold --branch main, thenmake 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, whichweb-verify-livecatches.
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 withcurl -Ithat docs pages carry exactly one policy; this is a launch item in docs/STATUS.md. make -i web-deployexits 0 from the outer make even though the script refused, because-iignores the inner failure. Run the target plainly. The Makefile's temporarywranglershim 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'sstyle-src-attrexceptions 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, awaitingOnnote and atextthat 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-statuslists 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 runsweb/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 (noorigin/mainrequirement) and uploads with the literal branchpreviewand--commit-hashset to HEAD, so it can never replace the production deployment. The result is verified withmake web-verify-live URL=https://preview.vaultfold.pages.dev, and the script prints theX-Robots-Tagthe 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 deployworks on the classic direct-upload project:make web-deploy-previewuploaded 359 files to thepreviewalias andmake web-verify-livepassed, 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'andstyle-src-attr 'unsafe-inline';/,/security/,/download/and/privacy/carry the strict policy, identical toheaders.tsoutput. The preview sendsx-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-previewfromstagingat de1dc0c: wrangler 4.151.0, 391 files,make web-verify-livepassed on 170 pages and the redirects.- One Content-Security-Policy on every URL checked.
/docs/pages and/pagefind/pagefind-worker.jsand/pagefind/pagefind.jscarry'wasm-unsafe-eval';/,/security/,/download/and/privacy/do not. NoSet-Cookieanywhere. - 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-deployfromorigin/mainat 7effdbe, wrangler 4.151.0, 391 files, and itsmake web-verify-livestep 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'andstyle-src-attr 'unsafe-inline'. NoSet-Cookieanywhere and nox-robots-tagon the apex.www.vaultfold.appdoes 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-protectionlink 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 settingenable_jsto false on the zone'sbot_managementsettings) and the Web Analytics beacon fromstatic.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, themailto:hello@vaultfold.appwaitlist 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-livenoticing, because those compare headers and cookies and never read the HTML a browser receives;make web-verify-livepassed 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 extendsverify-liveto fail on any script,/cdn-cgi/or cloudflareinsights reference the build did not emit and on a changedmailto: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-actionis'self'in both policies instead of'none'.- The only request-time code is one Pages Function serving
/api/waitlistand/api/waitlist/confirm, routed on those paths only by_routes.json. It sets the/*headers on its own responses fromfunctions/_generated/headers.json, which the header generator writes and the header check compares withdist/_headers. The deploy scripts run wrangler inweb/siteso thatfunctions/is compiled, and refuse to upload while the function's secrets are missing.