Security and authentication

The principle#

The authentication surface is therefore one route, and the other three simply check a session cookie.

The site key#

$argon2id$v=19$m=19456,t=2,p=1$<base64url salt>$<base64url digest>

Since the parameters live in the hash, hardening them later only requires regenerating the key — without touching the code.

The session#

Forging inline_edit only shows an interface whose writes will all be refused: routes check inline_session, never the marker. Replacing SESSION_SECRET instantly closes every open session.

Rate limiting#

Only the first protects a secret. The others protect the repository against a stolen session or a runaway script: they are wide, and a human editing their page never gets close.

The RATE_LIMIT binding

Counting needs state shared between function instances. Declare a key-value store named RATE_LIMIT on the host.

Host key-value stores are eventually consistent: two near-simultaneous attempts may read the same counter. Protection remains effective against brute force — which assumes thousands of attempts — but it is not exact to the unit. For strict counting, implement RateLimitStore on strongly consistent storage.

The order of checks#

Each route refuses in this order, and the order matters as much as the rules:

1. Rate

   Refusing an insistent caller does not require knowing who they are — and a stolen session must not be able to hammer the repository API.

2. Declared size

   No point holding 200 MB in memory only to discover it exceeds the cap. The header can lie: this is not the protection, it is the saving.

3. Identity

   verifyAuth, and nothing else. No route evaluates identity by itself.

4. Received size, shape, path, schema, lock, write

   The real cap is measured on received bytes, not on what was announced.

A size cap placed after reading the body protects nothing. That is why the tests call the routes directly rather than testing rules in isolation: it is the only way to verify the order.

What the write function verifies#

Why server-side sanitising does not use DOMPurify

DOMPurify needs a DOM, which the function runtime does not provide. With a pure-JavaScript DOM, DOMPurify raises no error: it sets isSupported to false and returns its input unchanged. Verified in the runtime, a <script> and an href="javascript:" came back intact.

So the server sanitiser rebuilds the fragment from its parse: only the whitelist is written back, the rest does not exist in the result. A test submits the same corpus to both implementations — browser and server — and compares the outputs: that is what guarantees they do not diverge.

Secrets#

On GitHub, the token must be:

• that of a dedicated machine account, not a person;
• fine-grained, limited to the site's repository only;
• with the Contents: Read and write permission, and nothing else.

Two automated checks stand guard: check-logs.mjs refuses a console.* that would evaluate a token, a hash, a cookie or an object containing them; check-secrets.mjs verifies no secret ends up in the build folder. See Checks and tests.

Key rotation#

To be done when someone leaves, in case of doubt, or periodically.

1. Generate

   npm run make:key

2. Replace EDITOR_KEY_HASH on the host

3. Replace SESSION_SECRET — if needed

   Do it on a departure or a doubt: it instantly closes every open session. Otherwise, current sessions stay valid until their 8-hour expiry.

4. Redeploy

   Variables are only re-read on deployment.

5. Send the new key

   Through a channel separate from the one carrying the editing address.

The old key stops working at step 4. There is no overlap period: that is deliberate — two valid keys at once is the kind of convenience one forgets to leave.

Verifying an installation#

# Content is indeed in the raw HTML
curl -s https://the-site.com/ | grep -c "a page title"          # → 1

# Writing is closed without a session
curl -s -o /dev/null -w "%{http_code}" -X POST https://the-site.com/api/save   # → 401

# No unexpected method is open
curl -s -o /dev/null -w "%{http_code}" https://the-site.com/api/save           # → 405

Then, by hand:

• Five wrong keys in a row on /admin end with a wait message. If the sixth attempt is still refused with “incorrect key”, rate limiting is not active — do not ship.
• The RATE_LIMIT binding is declared.
• Variables are set as runtime secrets, not build variables.
• The token is restricted to that single repository.
• The key has been delivered, and erased everywhere else.

What an attacker can, and cannot, do#

Moving to several users#

That need is met by replacing a single implementation: verifyAuth / createSession, with delegated authentication (Cloudflare Access, Supabase Auth, an identity provider). It is outside the v1 scope — but nothing in the rest of the code should prevent the switch, and that is exactly why no identity check exists anywhere else.