| Setup | Store |
|---|---|
| One Node process, and tests | SingleProcessReplayStore |
| More than one process, with Redis | RedisReplayStore from antlion-lacewing/redis |
| More than one process, with Postgres | PostgresReplayStore from antlion-lacewing/postgres |
| Something else shared | Your own ReplayStore with one atomic addIfAbsent(key, ttlSeconds) |
The Redis store sends one SET key 1 PX ttl NX per accepted request, the
Postgres store one INSERT ... ON CONFLICT DO UPDATE ... WHERE expired.
The in-memory store is atomic because its check and write have no await
between them, which holds in one JavaScript process only.
"More than one process" includes Node's cluster module, PM2 in cluster
mode, several containers behind a load balancer, serverless functions (each
warm instance is a process), and a blue/green pair that both take traffic.
tests/services/multi-process.test.ts sends one proof to four processes at
once: with a shared store one accepts it; with a memory store in each, all
four do.
Don't use SingleProcessReplayStore:
maxEntries. A full store refuses requests rather than
forget a proof early.A replay key lives maxProofAge + 6 seconds: the iat window, the 5
seconds a client clock may run ahead, and 1 second because both edges of the
window are inclusive. That is 66 seconds at the default maxProofAge of 60,
and 306 at the cap of 300.
live keys = peak accepted requests per second x (maxProofAge + 6)
Only accepted requests write a key.
SingleProcessReplayStore: set maxEntries above that number. 500
requests a second at the default is 33,000 keys, so maxEntries: 50_000
leaves room. When it is full, requests are refused with
replay-store-failed (cause: replay-store-full) until keys expire.deleteExpired() hasn't removed yet. Called once a minute, the table
stays under about twice the live count.A larger maxProofAge means a bigger store and a longer life for a stolen
proof; a smaller one refuses clients whose clocks run further behind. 60
seconds still forgives an unsynchronised laptop; 300 is the cap because
that is what oauth4webapi accepts.
import { RedisReplayStore } from "antlion-lacewing/redis";
const replay = new RedisReplayStore({ client: redis, prefix: "dpop:" }); // ioredis or node-redis
maxmemory-policy to noeviction. Under any volatile-* or
allkeys-* policy Redis evicts keys with a TTL when memory runs short,
and an evicted replay key is a proof that can be accepted again. Under
noeviction a full Redis refuses the write and the request is refused.Cluster can be passed as it is; a node-redis cluster needs the
one-line wrapper in the RedisClientLike docs. CI tests a single Redis 8
only; Cluster is untested.import { PostgresReplayStore } from "antlion-lacewing/postgres";
const replay = new PostgresReplayStore({ client: pool, table: "dpop_replay" }); // a pg Pool
setInterval(() => replay.deleteExpired().catch(console.error), 60_000); // or your own scheduler
PostgresReplayStore docs. Not UNLOGGED: an unlogged table is emptied
after a crash.synchronous_commit on for this table, or a crash loses the last
accepted keys. Asynchronous replication can lose them on failover the
same way; synchronous replication closes that.deleteExpired(). Antlion starts no timers. Nothing is refused
if you forget; the table grows.Both shared stores expire keys on the database server's clock.
A nonce is an HMAC over the second it was issued and the origin. Every node
with the same nonceSecrets and origin accepts every other node's
nonces; nothing else is shared.
Use the same list, in the same order, on every node. The first secret signs; all of them verify.
Each secret is at least 32 random bytes (the profile enforces it):
crypto.getRandomValues(new Uint8Array(32)).
Rotation takes three deploys, so no node receives a nonce signed with a secret it doesn't have yet:
[old, new].[new, old].maxProofAge plus 5 seconds has
passed, remove the old one: [new].Skipping step 1 is not a security problem. A node without the new secret
answers use_dpop_nonce with a nonce of its own, and the client retries.
iat may be up to 5 seconds ahead of the node
(fixed) and up to maxProofAge behind.now). Keep the clocks of every node sharing a store within 1 second of
each other. At 1 second or more, a proof accepted by the faster node at
the first instant it allows has its replay key expire before the slower
node stops accepting it, so the slower node accepts it again. The
"two nodes sharing a store" test in tests/compliance/time-replay.test.ts
checks both sides of that. NTP or chrony keeps ordinary servers well
inside it; containers share their host's clock.During a rolling deploy old and new nodes take traffic at once. Three
changes open a window of one replay per proof, lasting about
maxProofAge + 6 seconds after the last old node stops:
SingleProcessReplayStore to a shared
one, or changing the Redis prefix or the Postgres table. Old and new nodes
remember proofs in different places.maxProofAge, either way. A proof first accepted by a node with
the shorter setting can come back to a node with the longer one after its
key has gone.origin. This is a burst of refusals, since old and new nodes
refuse each other's proofs, not a replay window.If that matters, stop and start instead of rolling, or move to a shared store first and change the rest afterwards. Turning nonces on or off, and rotating secrets in the order above, open nothing.