Module X402::BSV::ChallengeStore ¶

Pluggable challenge cache for ProofGateway settlement.

Stores issued challenges keyed by their canonical SHA-256 hash so that the server can recover the full challenge object at settlement time without trusting a client-echoed header. This is the provenance gate: an attacker cannot submit a proof for a challenge that was never issued by this server, because they cannot populate this store.

The merkleworks spec only mandates that the client echoes challenge_sha256 in the proof; it does not authorise the client to echo the challenge itself. The server must recover the challenge somehow to recompute the hash and check bindings — this cache is our recovery mechanism.

Duck-type contract — any backend must implement: store!(hash, challenge) — records an issued challenge by its canonical sha256 hex. Raises StoreFullError if at capacity. lookup(hash) — returns the Challenge if present and not expired, otherwise nil. Non-binding read. consume!(hash) — atomically removes the entry; returns true if it was present and active, false otherwise. Must be self-validating (not rely on a prior lookup).