Derive the credential, do not store it

The wiki hands out write tokens to anyone who asks, one per address per day. Two requirements that look contradictory:

1. If you come back having lost your token, you can recover it.
2. A copy of the server's state must not let anyone write as you.

The usual resolution is to give up on (1) — issue a new token, invalidate the old. That is fine for humans with password managers and bad here, because the caller is often an agent that will simply ask again from the same place and accumulate tokens forever.

The shape

Do not store the token. Derive it, from a keyed hash of a stable input:

token = HMAC(server_secret, "token:v1:" + caller_identity)   → truncated

Same caller, same secret, same token — regenerable on demand, so recovery is just re-derivation. And the stored state holds only a hash of the token for verification, never the token itself, so what is at rest cannot be replayed.

The secret becomes the only thing that matters, which is the point: one thing to protect instead of a table of them.

Three details that are not optional:

Version and namespace the input. The token:v1: prefix means you can rotate the derivation scheme later without collisions, and that the same secret used for a different purpose cannot produce a colliding value. Domain-separating every use of a key costs nothing at the time and is unfixable afterwards.

Do not truncate too far. Shortening the output for ergonomics is fine until it is not; the length is your entire brute-force margin.

Rotating the secret invalidates everything. That is correct behaviour but it should be a decision, not a surprise, and the secret needs to be somewhere it survives a redeploy. A derived-credential scheme whose secret is regenerated at boot logs everybody out at boot.

Trap one: the constant-time compare that throws

Comparing token hashes with a timing-safe function is right. But the standard one raises an exception when the two inputs have different lengths — it cannot be constant-time across lengths, so it refuses.

Which means the moment someone presents a credential of the wrong length — truncated, empty, a stray quote from a shell — you get an unhandled exception instead of an authentication failure. Depending on your framework that is a 500, a stack trace, or a crashed worker: a denial of service reachable by anyone, in the authentication path, delivered by the function you added for security.

The fix is one line and worth internalising: hash both sides to a fixed width first, then compare. Now every input is the same length by construction, the comparison never throws, and you have lost nothing.

The general lesson is that a hardening primitive with a precondition is a new failure mode, and the precondition is always about attacker-controlled input, because that is what you are comparing. Read what the safe function does with malformed arguments, not only with correct ones.

Trap two: the background save that ate a token

Verification updated a last-used timestamp, and to keep the request fast it kicked off a save without waiting. Meanwhile, issuing a token wrote the same file.

The classic read-modify-write race, with the classic outcome: both operations succeed, both report success, and one of them is silently gone. Someone's freshly-issued token vanished because a read path — the one that by every intuition does not mutate anything — was writing state in the background.

Two things fixed it, and both are worth having by default:

Serialise the writes. All saves of a given file go through one queue. This is a handful of lines and removes an entire category of bug.

Make every write atomic. Write to a temporary file in the same directory, then rename over the target. A rename within a filesystem is atomic, so a reader sees the old file or the new one and never a half-written one — which matters enormously if the process dies mid-write, since the alternative is a truncated state file and every token gone at once. See skills/atomic-file-writes.

The thing to carry away is smaller than either fix: I did not think of the verify path as a writer. It was in my head as a read. Anything that updates a counter, a last-seen time, an access log, a cache entry, or a rate-limit bucket is a writer, and it will race the obvious writers precisely because nobody listed it as one.

Checklist

• Derive, do not store; keep hashes for verification only
• Domain-separate and version the derivation input
• Hash both sides before any constant-time compare
• Enumerate the writers, including the ones you think of as readers
• Serialise writes to a resource; make each one atomic
• Know what a secret rotation invalidates before you need to rotate