Skip to content

0065: The waitlist form and its function

  • Status: accepted (the maintainer asked for the form on 2026-11-16; the orchestrator's rulings of 2026-11-16 and the approved waitlist-form proposal)
  • Date: 2026-11-16
  • Change: waitlist-form
  • Amends: 0040 (a form, form-action 'self', and one function as the only request-time code) and 0050 (the waitlist is a form with double opt-in instead of a mailto: link, and its email promise is reworded)

Context

ADR 0050 launched the site with a waitlist that is a mailto: link to hello@vaultfold.app: the site collects no address, and every sign-up is a hand-written email the maintainer answers by hand. ADR 0040 made the site static with no request-time code, no form and form-action 'none', so a form needs both records amended.

On 2026-11-16 the maintainer asked for a real form: one field and one button on the page, a state for every outcome shown in the same card, and the address kept in one list at the mail provider the hosted service already uses (Resend). The constraints of the existing records still hold: marketing pages ship no JavaScript, the site sets no cookie and makes no third-party request from the browser, the policy names no other origin, and no Cloudflare challenge can protect a form because the zone features that inject scripts or set cookies stay off. The reasoning and the options weighed are in openspec/changes/waitlist-form/design.md.

Decision

  • A form with no script. The home and download pages carry a form that posts to /api/waitlist on the same origin. The function always answers 303 See Other to the posting page plus a state fragment (#waitlist-<state>), and the card shows the matching panel with CSS :target, so every outcome looks inline without a script. A JavaScript enhancement, a time-trap, a challenge and a notification mail per sign-up were considered and rejected (design.md 3).
  • One Pages Function, routed only where it is needed. The only request-time code is a Pages Function in web/site/functions/ serving /api/waitlist and /api/waitlist/confirm. _routes.json includes only those two paths, so nothing else ever invokes it. Every page is still a static file built from web/.
  • form-action 'self'. In both policies, marketing and docs. It allows the form to post to vaultfold.app and to nowhere else; every other directive is unchanged. Because the host does not apply _headers to a function's responses, the header generator also writes the /* headers to functions/_generated/headers.json, the function sets them on every response (plus Cache-Control: no-store, and X-Robots-Tag: noindex on a pages.dev host), and the header check fails when the two differ.
  • Same-origin by Sec-Fetch-Site, not Origin. Under the site's Referrer-Policy: no-referrer a form post carries Origin: null from any page, so the function accepts a post only with Sec-Fetch-Site: same-origin, refuses other values with 403, and answers a post without the header with the unavailable state, which offers the mailto: link. A request without CF-Connecting-IP did not come through Cloudflare and is answered the same way.
  • Double opt-in, one store. Submitting sends one confirmation mail with a signed link (HMAC-SHA256 over a purpose label, the address and the issue time, with a key id, valid 72 hours). Opening the link changes nothing; the confirm page's button adds the address to one Resend segment. Nothing is kept for an unconfirmed address except a keyed hash for 24 hours. The segment is the only store of addresses: no notification per sign-up, no copy anywhere else, open and click tracking off.
  • Abuse bounded, approximately in KV and exactly at Resend. A honeypot field, then per client IP (an IPv6 address by its /64) 5 accepted submissions per UTC hour, one mail per address (with any +tag removed) per 24 hours, and 40 confirmation mails per UTC day, kept as keyed hashes in Workers KV, checked before the address is parsed so busy never says anything about an address, and failing closed. Resend's idempotency key (one send per address per UTC day) and its own daily cap are the exact bounds. A zone rate-limiting rule is the outer layer. Every check-your-inbox answer waits a minimum delay, so a repeat and a new address look the same whenever Resend answers within it.
  • Secrets only as Pages secrets. The dedicated Resend key and the HMAC secret are set with wrangler pages secret put; only their names appear in the repository. wrangler.toml holds the bindings and variables and becomes the source of truth for them. The deploy scripts refuse to upload while a secret name is missing, while wrangler.toml enables the development log mode, or while the generated function headers differ from dist/_headers.
  • The waitlist promise. The promise beside the form becomes: "Your email is only used to send you early access to vaultfold. We add it only after you confirm it, keep it in one list at our mail provider Resend and nowhere else, and never share it. Every email has a link to leave, and we delete the list when early access ends." The privacy page says what is stored, where, for how long and how to leave. These are the claims trust.waitlist-email and trust.waitlist-store, with this record as their source.

Consequences

  • The site has request-time code for the first time. It is small, routed only on two paths, and holds two secrets; a fault in it can send mail as vaultfold.app or add unwanted addresses to the list, which is why it is built under the tier 3 rules (ADR 0053).
  • Every deploy needs the two secrets and the KV namespaces to exist, so the first deploy after the function lands waits for them.
  • The KV limits are approximate (eventually consistent, read then write); a coordinated attack from several IPs can spend the rest of Resend's shared daily allowance and delay the hosted service's sign-in mail until the next UTC day. The remedy, if it is ever needed, is moving sign-in mail to another provider.
  • Resend holds the list in the United States and keeps sent mail for 30 days; the privacy page says so. The list is deleted at 1.0, and the form is removed when anyone can download a build (design.md 11).
  • A browser without Sec-Fetch-Site (Safari before 16.4) cannot use the form and is offered the mailto: link instead.