2026-09-12 · 8 min read
- jwt
- replay-prevention
- security
The jti claim is a case-sensitive string that can provide a unique identifier for a JWT. Uniqueness supports replay controls only when the producer generates identifiers under a defined scope and the consumer remembers accepted values for the relevant time window.
A replay rule belongs to a token profile. Ordinary bearer access tokens are often intentionally reusable until expiration, while authorization assertions, logout tokens, proof tokens, or single-use action links may require one-time processing.
Define identity only after token validation
Verify the signature under an allowed algorithm and trusted key, then validate issuer, audience, token type, expiration, not-before, and any profile-specific claims. Build the replay key only from trusted validated values.
- Require jti only for profiles that assign it semantics.
- Set length and character limits before storage.
- Scope identifiers by issuer and purpose where required.
- Reject duplicate claim names during strict JSON processing.
Perform an atomic first-use decision
Use a compare-and-set or insert-if-absent operation that creates the replay record and returns whether it already existed. A separate lookup followed by insertion races when requests arrive concurrently.
Partitioning must preserve that atomic boundary. Per-process memory, eventually consistent replicas, or independent regions can each accept the same first use unless routing or a coordinated store establishes one authority.
Bound retention and failure behavior
Retain an accepted identifier through the latest time the token could pass validation, including permitted clock skew. Bound expiration-derived storage to protect the cache from far-future or malformed values, and monitor capacity and eviction.
- Use a monotonic deadline for local waits and validated wall time for claims.
- Document whether cache failure denies or permits processing.
- Do not expose raw tokens in keys, logs, or metrics.
- Separate replay rejection from malformed-token diagnostics.
Exercise concurrency and recovery
Use Flashman's JWT decoder only with synthetic tokens, timestamp converter for acceptance windows, hash and UUID tools for disposable fixture labels, and diff for expected decisions. Actual verification and replay storage belong in trusted server-side code.
Test simultaneous first use, repeated delivery after success and failure, same jti under different issuers and purposes, missing and malformed identifiers, expiry and skew boundaries, cache eviction, restart, network partition, failover, multi-region routing, algorithm and key rotation, and every token profile that is reusable or single-use.