fix: make idempotency reservation atomic and fail closed

[bscott]

MEDIUM finding from the 0.2.6 security review. The duplicate-send guard could be defeated two ways.

It was racy

CheckIdempotencyKey ran early (mail.go:323), RecordIdempotencyKey ran only after the send returned (mail.go:422), and the send sat between them. Two concurrent invocations with the same key both observed it as unused and both sent — precisely what the key exists to prevent.

It also failed open

loadIdempotencyStore returned an empty store when json.Unmarshal failed:

if err := json.Unmarshal(data, store); err != nil {
    return store, nil // Return empty store on parse error
}

A corrupt or truncated file silently disabled the protection instead of reporting it.

The fix

One marker file per key, created with O_CREATE|O_EXCL. That makes the reservation atomic across processes with no lock file, and leaves no parsed content that can fail open. Expiry comes from the file mtime.

The key is hashed (SHA-256) to form the filename, so a user-supplied key containing path separators cannot steer the marker out of the store — pinned by TestKeyCannotEscapeIdempotencyDir.

Callers now reserve before sending and release on failure, so a failed send is still retryable with the same key. A key already held returns the existing "already sent" response unchanged, so the user-visible behavior for genuine duplicates is the same.

Verification

TestReserveIdempotencyKeyIsAtomic races 32 goroutines on one key and asserts exactly one winner. Clean under -race across repeated runs. Nine tests total, covering expiry reclamation, release-then-retry, empty-key passthrough, and 0600 marker permissions.

Compatibility

The store format changes from idempotency.json to an idempotency/ directory, with no migration. Keys expire after 24 hours, so the old file simply goes unused and can be deleted. Worth a line in the release notes, which I've added to the CHANGELOG.

gofmt, go vet, go test ./... clean.

🤖 Generated with Claude Code