[nyuiela]

Summary

Closes #221.

Replaces the per-middleware closed-over Map with a process-wide MemoryIdempotencyStore that is shared across mounts, hard-capped, and coalesces concurrent same-key requests onto a single handler execution.

Design decisions

1. Where the state belongs. Process-wide in-memory store shared by every idempotency() mount that does not inject its own store. This service still has no persistence layer (compression / cors / express only), so bolting on Redis here would invent a second stack ahead of the tracked persistence issue. Cross-replica duplicates remain a known limit until that store lands; this PR closes the within-process holes (cross-mount + concurrent) without an external dependency. Sequencing: swap IdempotencyStore for a Redis/DB implementation once persistence exists — the middleware options already accept an injectable store.

2. What a replay returns. Keep stored-response replay (status + JSON body). Clients of settlement APIs expect a safe retry to return the original outcome, not a conflict that forces a separate GET. Returning 409/422 on every duplicate would break the existing contract and the curl walkthrough in the README.

3. Eviction and bounds. Default TTL unchanged (IDEMPOTENCY_TTL_MS / 24h). Hard cap default 1024 entries: purge expired on write, then drop soonest-to-expire live entries until under the cap. MemoryIdempotencyStore(maxEntries) is injectable for tighter bounds in tests.

Sensitive header audit

Cached entries store only { status, body, expiresAt, bodyHash }. Response headers (Set-Cookie, Authorization, custom secrets) are never written into the cache. Covered by a regression test.

Public options

IdempotencyOptions stays backward compatible: ttlMs unchanged. Additive optional fields: store, maxEntries (used when constructing a private store in tests; production continues to use the process-wide default).

Test plan

• Cross-instance: two middleware instances, shared store, same key → one execution
• Bound: 3 * maxEntries distinct keys → store.size() <= maxEntries
• Concurrent same-key → one handler run
• Keyless mutating requests unaffected
• Header audit: cached entry has no header fields
• npm run lint && npm run build && npm test (42 suites / 493 tests)