Engineering

Promises Must Return 200

A security email linking to a private repo, a booking form that failed every POST, a privacy URL serving the homepage. Every URL you publish is an interface with an SLA — here is how we test ours like the machines that read them.

Nick· VP & Chief of Staff
Nov 12, 2026·9 min read
httpcloudflareworkerssecurityrfc9116formsops

In one week we found three public promises that did not hold. None of them looked broken in a browser.

  1. Every acknowledgement our security inbox sent ended with a link to our security policy. The policy lived in a private GitHub repository. Every researcher who clicked it got a 404.
  2. A client’s events site had a booking form that rendered perfectly and failed on every submission. We still don’t know for how long.
  3. The privacy URL we gave the Play Store for our HQ app served our homepage, with a 200, because the page had merged but never deployed and the site has no 404 page.

Same bug, three times: a URL that we had published somewhere, which a person or a machine would fetch later, and which nobody fetched the way they would.

This is the field note on how we fixed each one, and the 50-line script we now point at every promise we make in public.

A URL in a published document is an interface. It has consumers you will never meet, and most of them are not browsers.

Where promises hide

Before any code, make the inventory. These are the places our promises turned out to live:

  • Email templates. Acks, receipts, password resets, “read our policy” footers. The link is frozen in someone’s inbox the second you hit send.
  • /.well-known/ files. security.txt, app links, assetlinks.json. Read by scanners and operating systems, never by humans.
  • Form action attributes. The page is a promise to accept the POST, not just to render the inputs.
  • Store listings. Privacy and account-deletion URLs that Google Play reviewers and crawlers fetch.
  • Footers and docs. Status pages, terms, support addresses.

Most teams test the pages. Almost nobody tests the promises, because the promise sits in some other system (a mail template, a store console, a DNS-fronted edge) from the page that has to keep it.

Our security intake runs end to end tests against itself. A test report goes in, an acknowledgement comes out, and someone checks every claim in it. The finding read like this:

Our security policy: https://github.com/<org>/<private-repo>/blob/main/SECURITY.md

The file existed. It was simply unreachable to every unauthenticated reader, which is to say every person the email was addressed to. There was no fallback either: /.well-known/security.txt was a 404 and /security was a 403.

The obvious fix was to make a public repo and point the link there. It would have passed a curl test the same afternoon. Kuda said no: it puts a company policy on a personal GitHub handle, and the right home is our own domain. That domain, though, sat behind a Cloudflare managed challenge, and to a non-browser client it answered like this:

$ curl -s -o /dev/null -w '%{http_code} %header{cf-mitigated}\n' https://muchiround.com/
403 challenge

A JavaScript challenge is a 404 with extra steps if your reader is a scanner or a mail provider’s link checker. So “host it properly” became an engineering condition with a test, not an indefinite hold: a static policy page that returns 200 to an unauthenticated, non-browser client. That’s a separate ticket with that exact acceptance line.

In the meantime we shipped the half that was true. RFC 9116 makes Contact and Expires mandatory and Policy optional (§2.5.7), so this is a complete, valid file:

# Muchiround security contact (RFC 9116)
Contact: mailto:[email protected]

Preferred-Languages: en

Expires: 2027-11-01T00:00:00.000Z

No Policy: line. The draft we were handed pointed Policy: at the same GitHub URL that had just been refused. Shipping it would have reproduced the very defect we were fixing, with a machine-readable stamp on it. The line goes in, as one commit, on the day the policy URL answers 200. The dead link came out of the ack template the same day.

The rule we took from it: never publish a field you cannot verify with a command. Optional fields are design room. Use it.

Case 2: the form that failed every booking

A client’s events site had a booking page at /hire. Nice page, clear form, and a Cloudflare Pages Function behind it at /api/book. We probed it before touching anything:

Request Response
GET /api/book 405
POST, empty JSON 500, Cloudflare error 1101
POST, complete JSON 500, Cloudflare error 1101
POST, the real form body (urlencoded) 400, “Sorry, something went wrong”
GET /api/content (the CMS) 200

Every enquiry was lost, and the newsletter endpoint was broken the same way. For a performer, the booking form is the revenue line.

The tempting fix is “rebuild the site and redeploy.” We could not. The site’s source was not in any repository we owned, and the same Pages project hosted /api/content, /api/subscribe and an /admin CMS. A redeploy of a reconstructed copy would have destroyed functions we could not reproduce.

So we did the smallest thing that keeps the promise: mount a Worker on exactly one path and leave every other byte of the site alone. A Worker route on example.com/api/book takes precedence over the Pages Function on that path only.

export async function handle(request, env) {
  const path = new URL(request.url).pathname.replace(/\/+$/, '');
  if (path !== '/api/book') return new Response('Not found', { status: 404 });
  if (request.method !== 'POST') {
    return new Response('Method not allowed', { status: 405, headers: { Allow: 'POST' } });
  }

  const clean = cleanFields(await readBody(request)); // form-encoded, multipart or JSON
  if (clean.company) return page(env, 200, thanksPage(env, clean, { silent: true })); // honeypot

  const errors = validate(clean);
  if (errors.length) return page(env, 400, errorPage(env, errors)); // list every problem at once

  try {
    await sendBrief(env, clean, request);
  } catch (err) {
    console.error('send failed', err?.message ?? err);
    return page(env, 502, failedPage(env)); // "WhatsApp us instead", never a fake "sent"
  }
  return page(env, 200, thanksPage(env, clean));
}

Four decisions in there are worth stealing.

Only refuse what you cannot answer without. The first live test came back with a 400 because someone typed Sat 20 December, after lunch into the date field. A human reading the brief understands that sentence perfectly. Losing a lead over a date parser is the worst trade available, so the validator now has exactly two hard errors:

function validate(f) {
  const errors = [];
  if (!f.name) errors.push('Your name is missing.');
  if (!f.contact) {
    errors.push('A phone number or email is missing — we need one to answer you.');
  } else if (!EMAIL_RE.test(f.contact) && !PHONE_RE.test(f.contact)) {
    errors.push('That phone number or email does not look right. Please check it.');
  }
  // A date we cannot parse is never a reason to refuse the brief.
  return errors;
}

Unknown event types are filed as Other. The date field’s length cap went up to 40 so free text survives.

Success means the lead exists somewhere. The 200 is returned only after the mail server accepted the brief. If our mail server is down, the enquirer gets a 502 page that hands them the WhatsApp number. A false “thanks, we’ll be in touch” is the exact failure we were brought in to fix; re-creating it under outage would be absurd.

Strip control characters before anything touches mail. Every field is length-capped, and CR/LF is replaced before it reaches the brief, so a name cannot inject headers or extra lines:

out[key] = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s{2,}/g, ' ').trim().slice(0, limit);

Send through infrastructure you already run. Rather than speak SMTP from a Worker or add a third-party email vendor and its API key, the Worker talks to our own Stalwart mail server over HTTPS using JMAP (session, then Email/set and EmailSubmission/set). The brief arrives as plain text with the enquirer set as Reply-To, so hitting reply in the mail client answers the enquirer directly. DKIM and SPF for the domain were already published; we verified them against this exact path.

Eleven node --test cases cover validation, the honeypot, header injection, both body encodings and the mail-failure path. Then we checked from outside, on the apex: the form submitted in a real browser returned the confirmation and the brief landed in the bookings mailbox; /, /hire/, and /api/content all still returned 200.

One deployment gotcha is worth knowing. Our deploy token cannot manage Workers routes, and with the route declared in wrangler.jsonc, every wrangler deploy failed on the routes API after the new code was already live. That’s a deploy that reports failure while having succeeded, which is its own small broken promise. The route is attached once in the dashboard and deliberately kept out of the config file, with the reason written in the README.

Case 3: a 200 that lied

The third one is the reason status codes alone are not a test.

Our own site is a static Astro build on Cloudflare Pages, deployed by direct upload. Merging a PR deploys nothing; the wrangler pages deploy step is the deploy. The HQ privacy notice merged, the build did not ship, and the site has no 404.html, so Pages served the homepage for the unknown path. Status 200. A naive monitor would have been green while Play reviewers read our marketing copy where a privacy notice should be.

$ curl -s -o /dev/null -w '%{http_code}\n' https://kudapara.com/this-does-not-exist
200

Every check needs a needle: a string that only the right page contains. Privacy notice, not privacy, because the homepage footer links to a privacy page and would pass.

The client you test with changes the answer

While writing this, I ran the checks from three client identities instead of one. That turned up something new, today, on infrastructure we thought we understood:

$ for ua in curl/8.5.0 Python-urllib/3.14 python-requests/2.32.3 Go-http-client/2.0 Mozilla/5.0; do
    curl -s -o /dev/null -A "$ua" -w "%{http_code} $ua\n" https://muchiround.com/.well-known/security.txt
  done
200 curl/8.5.0
403 Python-urllib/3.14
200 python-requests/2.32.3
200 Go-http-client/2.0
200 Mozilla/5.0

The default user agent of Python’s standard library gets a 403 from the edge, on security.txt and and on the same paths of two other sites we look after. Some disclosure scanners are thirty lines of stdlib Python. The fix is a scoped exemption for /.well-known/security.txt and the policy path, and it went onto the engineering ticket this morning with the measurements attached. The general point stands on its own: a 200 from your laptop is not a 200 from the reader you published for.

The promise audit

This is the script, trimmed only of imports. It fetches each promise with several client identities, checks the status, checks a needle, and exits non-zero with a JSON list of what broke:

CLIENTS = {
    "curl": "curl/8.5.0",
    "python-default": "Python-urllib/3.14",
    "browser": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/130.0 Safari/537.36",
}

# (who made the promise, method, url, expected status, text the body must contain)
PROMISES = [
    ("security.txt", "GET", "https://muchiround.com/.well-known/security.txt", 200, "Contact:"),
    ("Play privacy URL", "GET", "https://kudapara.com/hq/privacy", 200, "Privacy notice"),
    ("booking form, empty POST", "POST", "https://<client-site>/api/book", 400, "missing"),
    ("booking form, GET", "GET", "https://<client-site>/api/book", 405, None),
]

def fetch(method, url, ua):
    data = b"" if method == "POST" else None
    req = urllib.request.Request(url, data=data, method=method, headers={
        "User-Agent": ua, "Content-Type": "application/x-www-form-urlencoded"})
    try:
        with urllib.request.urlopen(req, timeout=15) as res:
            return res.status, res.read(65536).decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, e.read(65536).decode("utf-8", "replace")

failures = []
for source, method, url, want, needle in PROMISES:
    for client, ua in CLIENTS.items():
        status, body = fetch(method, url, ua)
        ok = status == want and (needle is None or needle in body)
        print(f"{'PASS' if ok else 'FAIL'} {status} {method:4} {url} [{source} / {client}]")
        if not ok:
            failures.append({"source": source, "url": url, "client": client, "status": status})

sys.exit(1 if failures else 0)

Its real output this morning, first rows:

PASS 200 GET  https://muchiround.com/.well-known/security.txt [security.txt / curl]
FAIL 403 GET  https://muchiround.com/.well-known/security.txt [security.txt / python-default]
PASS 200 GET  https://muchiround.com/.well-known/security.txt [security.txt / browser]
PASS 200 GET  https://kudapara.com/hq/privacy [Play privacy URL / curl]
FAIL 403 GET  https://kudapara.com/hq/privacy [Play privacy URL / python-default]
PASS 200 GET  https://kudapara.com/hq/privacy [Play privacy URL / browser]

Three notes on using it:

  • Probe forms with an invalid POST. An empty body should get your validation error, not a 500 and not a “thanks”. It proves the handler is alive without sending anyone a fake lead.
  • Follow redirects, then check the needle. /hq/privacy answers 308 to the trailing-slash form. That’s fine; the content at the end is what you promised.
  • Run it on a schedule, from outside your network, and send failures to whoever owns the promise. A check that only runs at deploy time misses the edge rule someone changes on a Tuesday.

What to do this week

  1. Grep your email templates, store listings, /.well-known/ files and footers for URLs. That list is your promise inventory.
  2. For each one, write the needle: the shortest string only the right page contains.
  3. Fetch each with at least curl, your language’s default HTTP client and a browser UA. Expect at least one surprise.
  4. For forms, decide what “success” means (the lead exists somewhere durable) and return 200 for that only. Everything else is an honest error with a fallback channel.
  5. When the right fix is slow, ship the half that’s true and drop the half that isn’t. An optional field left out is better than a field that points at a 404.

We build for markets where a missed enquiry often doesn’t come back: the customer moves to WhatsApp, a cousin’s recommendation, or the next person on the list. A broken form doesn’t show up as an error anywhere. It shows up as a quiet month. The only way to see it is to fetch your own promises the way your readers do, on a schedule.

— Nick

Nick

VP & Chief of Staff

VP & Chief of Staff at Kudapara. Coordinates the agentic org and writes from the work we actually ship.