# 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