Skip to main content

hyprstream_rpc/proof/
admission.rs

1//! Proof replay admission and challenge manager wiring.
2//!
3//! "Admitted once" means once per **replay admission domain** — the complete
4//! set of verifier instances that can admit requests for one service domain —
5//! never once per node (§4.6). A deployment satisfies that with exactly one
6//! of three shapes, and every store must say which one it is:
7//!
8//! 1. a single verifier instance;
9//! 2. a shared store with linearizable check-and-insert; or
10//! 3. per-node stores with **mandatory** replay-namespace-affine routing,
11//!    where failover to a node holding no history for that namespace denies
12//!    rather than admits.
13//!
14//! v16 credentials are Reusable-only: replay admission is keyed by the proof,
15//! so many fresh proofs may use one credential. The `OneShotTransaction`
16//! credential-use profile and its atomic consume-once path were cut from v16
17//! scope (operator decision `DECISION-defer-oneshot-credentials-2026-08-20`)
18//! and are deferred to a future amendment.
19
20use std::collections::{BTreeMap, HashMap};
21use std::sync::OnceLock;
22
23use anyhow::Result;
24
25use super::{ProofDisposition, RequestId};
26
27/// A capacity-bounded set of admitted keys with **expiry-ordered** reclamation.
28///
29/// Each key holds a signed expiry. A secondary `BTreeMap` orders keys by
30/// `(expires_at, seq)`, so garbage collection pops only the records that have
31/// actually expired — from the front, in expiry order — and stops at the first
32/// unexpired one. Reclamation therefore touches O(expired) records, never the
33/// whole partition, so a non-replay admission far below capacity is O(log n),
34/// not an O(n) full scan on every request. The invariants Opus F-D must
35/// preserve are unchanged: an unexpired accepted record is never evicted, and a
36/// full partition fails closed rather than making room by eviction.
37struct ExpiryMap<K: std::hash::Hash + Eq + Clone> {
38    /// key -> (expires_at, seq)
39    entries: HashMap<K, (u64, u64)>,
40    /// (expires_at, seq) -> key, for expiry-ordered reclamation.
41    by_expiry: BTreeMap<(u64, u64), K>,
42    /// Monotonic tie-breaker so equal expiries never collide in `by_expiry`.
43    next_seq: u64,
44}
45
46impl<K: std::hash::Hash + Eq + Clone> Default for ExpiryMap<K> {
47    fn default() -> Self {
48        Self {
49            entries: HashMap::new(),
50            by_expiry: BTreeMap::new(),
51            next_seq: 0,
52        }
53    }
54}
55
56impl<K: std::hash::Hash + Eq + Clone> ExpiryMap<K> {
57    /// Reclaim only the records whose signed expiry is at or before `now`,
58    /// in expiry order, stopping at the first unexpired record.
59    // A `while let` on `first_key_value()` would hold an immutable borrow of
60    // `by_expiry` across the `remove()` below (the scrutinee temporary lives to
61    // the end of the loop body), so the peek is a separate statement that copies
62    // the key and releases the borrow first.
63    #[allow(clippy::while_let_loop)]
64    fn gc(&mut self, now: u64) {
65        loop {
66            // Peek the earliest-expiring record and copy its ordering key, so
67            // the immutable borrow ends before the mutation below.
68            let front = match self.by_expiry.first_key_value() {
69                Some((&front, _)) => front,
70                None => break,
71            };
72            if front.0 > now {
73                break; // earliest-expiring record is still live; nothing more to reclaim.
74            }
75            if let Some(key) = self.by_expiry.remove(&front) {
76                // Only drop the primary entry if it still points at this record;
77                // a re-inserted key would carry a newer (exp, seq).
78                if self.entries.get(&key) == Some(&front) {
79                    self.entries.remove(&key);
80                }
81            }
82        }
83    }
84
85    /// Admit `key` under fail-closed capacity, or report a replay.
86    fn admit(&mut self, key: &K, expires_at: u64, max: usize, now: u64) -> ProofAdmissionResult {
87        if self.entries.contains_key(key) {
88            return ProofAdmissionResult::Replayed;
89        }
90        // Reclaim expired records first — bounded to the expired set, never a
91        // full-partition scan.
92        self.gc(now);
93        if self.entries.len() >= max {
94            return ProofAdmissionResult::Failed;
95        }
96        let seq = self.next_seq;
97        self.next_seq = self.next_seq.wrapping_add(1);
98        self.entries.insert(key.clone(), (expires_at, seq));
99        self.by_expiry.insert((expires_at, seq), key.clone());
100        ProofAdmissionResult::Admitted
101    }
102}
103
104// ---------------------------------------------------------------------------
105// Replay admission store
106// ---------------------------------------------------------------------------
107
108/// The replay admission key: (signer namespace thumbprint, request_id).
109///
110/// The thumbprint is the credential-bound primary signer-suite thumbprint for
111/// authenticated proofs and the content-bound key-set thumbprint for unattributed
112/// ones. It is produced by verification, never taken from the wire.
113#[derive(Debug, Clone, PartialEq, Eq, Hash)]
114pub struct ProofReplayKey {
115    pub signer_thumbprint: [u8; 32],
116    pub request_id: RequestId,
117}
118
119/// A read-only authorization query derived from one holder-signed request.
120/// Separate from dispatch admission: list handlers may check several resources
121/// for one request, but the same derived query is admitted only once.
122#[derive(Debug, Clone, PartialEq, Eq, Hash)]
123pub struct MediatedQueryReplayKey {
124    pub signer_thumbprint: [u8; 32],
125    pub request_id: u64,
126    /// Legacy envelope IDs are client-local counters; the signed random nonce
127    /// distinguishes fresh requests from different clients using one holder.
128    pub request_nonce: [u8; 16],
129    pub mediator: String,
130    pub resource: String,
131    pub operation: String,
132}
133
134/// Opaque namespace and identity digests for a one-use source credential.
135/// This is separate from holder-proof request IDs, so consuming a login token
136/// cannot collide with a later Registry/Model proof admission.
137#[derive(Debug, Clone, PartialEq, Eq, Hash)]
138pub struct CredentialReplayKey {
139    pub issuer_client_namespace: [u8; 32],
140    pub credential_identity: [u8; 32],
141}
142
143/// The outcome of a replay admission check.
144#[derive(Debug, Clone, Copy, PartialEq, Eq)]
145pub enum ProofAdmissionResult {
146    /// Admitted exactly once in this domain.
147    Admitted,
148    /// This exact key was already admitted.
149    Replayed,
150    /// The store could not guarantee admission — capacity, backend
151    /// unavailability, or a guarantee the deployment does not provide. Always
152    /// a denial; never an admission.
153    Failed,
154}
155
156/// How a deployment satisfies domain-wide "admitted once" (§4.6).
157#[derive(Debug, Clone, Copy, PartialEq, Eq)]
158pub enum ReplayDomainGuarantee {
159    /// Exactly one verifier instance admits for this service domain.
160    SingleVerifierInstance,
161    /// A shared store providing linearizable check-and-insert across every
162    /// verifier in the domain.
163    LinearizableSharedStore,
164    /// Per-node stores with mandatory replay-namespace-affine routing. Every
165    /// admission must first confirm this node owns the key's namespace.
166    NamespaceAffineRouting,
167}
168
169/// Proof replay admission store.
170///
171/// Implementations are the substrate (in-process for a single verifier, or a
172/// shared linearizable backend); this trait is the only admission surface.
173pub trait ProofReplayStore: Send + Sync {
174    /// Which domain-wide guarantee this deployment provides. Dispatch refuses
175    /// to admit under a guarantee the store cannot honour for the key at hand.
176    fn domain_guarantee(&self) -> ReplayDomainGuarantee;
177
178    /// Whether this node owns the replay namespace for `signer_thumbprint`.
179    ///
180    /// Only consulted under [`ReplayDomainGuarantee::NamespaceAffineRouting`],
181    /// where a node that does not own the namespace holds none of its history
182    /// and MUST deny rather than admit. The other guarantees own every
183    /// namespace by construction.
184    fn owns_namespace(&self, signer_thumbprint: &[u8; 32]) -> bool {
185        let _ = signer_thumbprint;
186        !matches!(
187            self.domain_guarantee(),
188            ReplayDomainGuarantee::NamespaceAffineRouting
189        )
190    }
191
192    /// Atomically admit a fresh key or reject a replay, within the partition
193    /// for `partition`. Capacity pressure MUST NOT evict an unexpired accepted
194    /// record: the partition fails closed instead.
195    fn check_and_insert(
196        &self,
197        partition: ProofDisposition,
198        key: &ProofReplayKey,
199        expires_at: u64,
200    ) -> ProofAdmissionResult;
201
202    /// Dedicated mediated-query domain. Backends that do not implement this
203    /// atomic admission deny; they must never silently reuse dispatch keys.
204    fn check_and_insert_mediated(
205        &self,
206        _key: &MediatedQueryReplayKey,
207        _expires_at: u64,
208    ) -> ProofAdmissionResult {
209        ProofAdmissionResult::Failed
210    }
211
212    /// Atomically consume one verified source credential through its expiry.
213    /// Backends that do not provide a separate shared credential partition
214    /// deny rather than alias it into proof-request replay state.
215    fn check_and_insert_credential(
216        &self,
217        _key: &CredentialReplayKey,
218        _expires_at: u64,
219    ) -> ProofAdmissionResult {
220        ProofAdmissionResult::Failed
221    }
222}
223
224/// In-memory replay store for a deployment with exactly one verifier instance.
225///
226/// Partitioned by disposition, so saturation of the unattributed partition can
227/// neither delay nor deny authenticated admission. Capacity fails closed: an
228/// unexpired accepted record is never evicted to make room.
229///
230/// This shape is sound **only** as
231/// [`ReplayDomainGuarantee::SingleVerifierInstance`]. A multi-instance
232/// deployment needs a shared linearizable backend implementing the same trait;
233/// there is deliberately no in-memory constructor that claims a guarantee this
234/// type cannot provide.
235pub struct InMemoryProofReplayStore {
236    authenticated: parking_lot::Mutex<ExpiryMap<ProofReplayKey>>,
237    unattributed: parking_lot::Mutex<ExpiryMap<ProofReplayKey>>,
238    mediated: parking_lot::Mutex<ExpiryMap<MediatedQueryReplayKey>>,
239    credentials: parking_lot::Mutex<ExpiryMap<CredentialReplayKey>>,
240    max_per_partition: usize,
241}
242
243impl InMemoryProofReplayStore {
244    /// Construct the single-verifier-instance store. The name is the
245    /// deployment assertion: installing this in a multi-instance domain breaks
246    /// the domain-wide guarantee.
247    pub fn single_verifier_instance(max_per_partition: usize) -> Self {
248        Self {
249            authenticated: Default::default(),
250            unattributed: Default::default(),
251            mediated: Default::default(),
252            credentials: Default::default(),
253            max_per_partition,
254        }
255    }
256
257    fn lock(
258        &self,
259        partition: ProofDisposition,
260    ) -> parking_lot::MutexGuard<'_, ExpiryMap<ProofReplayKey>> {
261        match partition {
262            ProofDisposition::Authenticated => self.authenticated.lock(),
263            ProofDisposition::Unattributed => self.unattributed.lock(),
264        }
265    }
266}
267
268impl ProofReplayStore for InMemoryProofReplayStore {
269    fn domain_guarantee(&self) -> ReplayDomainGuarantee {
270        ReplayDomainGuarantee::SingleVerifierInstance
271    }
272
273    fn check_and_insert(
274        &self,
275        partition: ProofDisposition,
276        key: &ProofReplayKey,
277        expires_at: u64,
278    ) -> ProofAdmissionResult {
279        let now = current_unix_seconds();
280        let max = self.max_per_partition;
281        self.lock(partition).admit(key, expires_at, max, now)
282    }
283
284    fn check_and_insert_mediated(
285        &self,
286        key: &MediatedQueryReplayKey,
287        expires_at: u64,
288    ) -> ProofAdmissionResult {
289        let now = current_unix_seconds();
290        if expires_at <= now {
291            return ProofAdmissionResult::Failed;
292        }
293        self.mediated
294            .lock()
295            .admit(key, expires_at, self.max_per_partition, now)
296    }
297
298    fn check_and_insert_credential(
299        &self,
300        key: &CredentialReplayKey,
301        expires_at: u64,
302    ) -> ProofAdmissionResult {
303        self.credentials.lock().admit(
304            key,
305            expires_at,
306            self.max_per_partition,
307            current_unix_seconds(),
308        )
309    }
310}
311
312// ---------------------------------------------------------------------------
313// Single-verifier sole-membership lease (§4.6 topology enforcement)
314// ---------------------------------------------------------------------------
315
316/// An exclusive, process-lifetime lease proving this process is the **sole**
317/// verifier for a replay admission domain (§4.6, shape 1).
318///
319/// The `SingleVerifierInstance` guarantee is only sound if exactly one process
320/// admits for the domain. An operator env string alone cannot establish that —
321/// two replicas can each set it and silently recreate a per-process replay
322/// split. This lease converts the claim into an OS-enforced fact: it holds an
323/// **exclusive, non-blocking** advisory lock (`flock(LOCK_EX|LOCK_NB)`) on an
324/// operator-configured lease path for the whole process lifetime. A second
325/// process attempting to acquire the same lease fails, so its proof admission
326/// stays closed rather than admitting under a guarantee it cannot honour.
327///
328/// The lease path's storage defines the domain the exclusion spans: a
329/// same-host domain uses any local path; a multi-host domain MUST place the
330/// lease on storage shared and lock-coherent across every verifier (an
331/// operator responsibility the mechanism cannot infer, but which — unlike a
332/// bare env string — it does enforce wherever the lock is actually coherent).
333#[cfg(not(target_arch = "wasm32"))]
334pub struct SingleVerifierLease {
335    // The open file whose exclusive flock is released when this handle drops.
336    // Kept process-global so the lock outlives startup.
337    _file: std::fs::File,
338    path: std::path::PathBuf,
339}
340
341#[cfg(not(target_arch = "wasm32"))]
342impl SingleVerifierLease {
343    /// Acquire the exclusive sole-verifier lease, or fail closed.
344    ///
345    /// Returns `Err` when another process already holds the lease (the domain
346    /// already has a verifier) or the path cannot be opened/locked. The caller
347    /// MUST NOT install a `SingleVerifierInstance` store without holding this.
348    pub fn acquire(path: &std::path::Path) -> Result<Self> {
349        use nix::fcntl::{flock, FlockArg};
350        use std::os::fd::AsRawFd;
351
352        let file = std::fs::OpenOptions::new()
353            .create(true)
354            .truncate(false)
355            .read(true)
356            .write(true)
357            .open(path)
358            .map_err(|e| {
359                anyhow::anyhow!("cannot open single-verifier lease {}: {e}", path.display())
360            })?;
361        // Non-blocking exclusive lock: a second holder fails immediately rather
362        // than queueing, so a misconfigured second replica denies at once.
363        flock(file.as_raw_fd(), FlockArg::LockExclusiveNonblock).map_err(|e| {
364            anyhow::anyhow!(
365                "another process already holds the single-verifier lease {} \
366                 (this domain already has a verifier): {e}",
367                path.display()
368            )
369        })?;
370        Ok(Self {
371            _file: file,
372            path: path.to_path_buf(),
373        })
374    }
375
376    /// The lease path (for diagnostics).
377    pub fn path(&self) -> &std::path::Path {
378        &self.path
379    }
380}
381
382// The held lease is parked here so the exclusive lock lives for the whole
383// process, not just past startup. Dropping it would release the lock and let a
384// second verifier acquire it.
385#[cfg(not(target_arch = "wasm32"))]
386static SINGLE_VERIFIER_LEASE: OnceLock<SingleVerifierLease> = OnceLock::new();
387
388/// Park an acquired sole-verifier lease for the process lifetime.
389#[cfg(not(target_arch = "wasm32"))]
390pub fn hold_single_verifier_lease(
391    lease: SingleVerifierLease,
392) -> std::result::Result<(), SingleVerifierLease> {
393    SINGLE_VERIFIER_LEASE.set(lease)
394}
395
396// Process-global registration. There is no auto-install: an absent store is a
397// denial, never a locally-defaulted admission.
398static PROOF_REPLAY_STORE: OnceLock<Box<dyn ProofReplayStore>> = OnceLock::new();
399
400pub fn set_global_proof_replay_store(
401    store: Box<dyn ProofReplayStore>,
402) -> std::result::Result<(), Box<dyn ProofReplayStore>> {
403    PROOF_REPLAY_STORE.set(store)
404}
405
406pub fn global_proof_replay_store() -> Option<&'static dyn ProofReplayStore> {
407    PROOF_REPLAY_STORE.get().map(|s| &**s)
408}
409
410/// Admit one request proof, enforcing the domain guarantee before the store
411/// is consulted.
412///
413/// Under namespace-affine routing a node that does not own the key's namespace
414/// holds none of its history, so it denies instead of admitting locally.
415pub fn admit_request_proof(
416    store: &dyn ProofReplayStore,
417    partition: ProofDisposition,
418    key: &ProofReplayKey,
419    expires_at: u64,
420) -> ProofAdmissionResult {
421    if !store.owns_namespace(&key.signer_thumbprint) {
422        return ProofAdmissionResult::Failed;
423    }
424    store.check_and_insert(partition, key, expires_at)
425}
426
427/// Validate mediated-query dimensions on borrowed values, before any owned
428/// copy is materialized for the replay key (Sol finding: resource/operation
429/// were copied ahead of these checks).
430pub fn validate_mediated_query_dimensions(
431    mediator: &str,
432    resource: &str,
433    operation: &str,
434) -> Result<()> {
435    anyhow::ensure!(
436        !mediator.is_empty() && mediator.len() <= 128,
437        "mediated mediator name out of bounds"
438    );
439    anyhow::ensure!(
440        !resource.is_empty() && resource.len() <= 4096,
441        "mediated resource out of bounds"
442    );
443    anyhow::ensure!(
444        !operation.is_empty() && operation.len() <= 128,
445        "mediated operation out of bounds"
446    );
447    Ok(())
448}
449
450/// Admit a bounded mediated query under the installed store's topology.
451pub fn admit_mediated_query(
452    store: &dyn ProofReplayStore,
453    key: &MediatedQueryReplayKey,
454    expires_at: u64,
455) -> ProofAdmissionResult {
456    if validate_mediated_query_dimensions(&key.mediator, &key.resource, &key.operation).is_err()
457        || !store.owns_namespace(&key.signer_thumbprint)
458        || expires_at <= current_unix_seconds()
459    {
460        return ProofAdmissionResult::Failed;
461    }
462    store.check_and_insert_mediated(key, expires_at)
463}
464
465// ---------------------------------------------------------------------------
466// Process-global challenge manager
467// ---------------------------------------------------------------------------
468
469static CHALLENGE_MANAGER: OnceLock<super::challenge::ChallengeManager> = OnceLock::new();
470
471/// Install a challenge manager for the process.
472pub fn set_global_challenge_manager(
473    mgr: super::challenge::ChallengeManager,
474) -> std::result::Result<(), super::challenge::ChallengeManager> {
475    CHALLENGE_MANAGER.set(mgr)
476}
477
478pub fn global_challenge_manager() -> Option<&'static super::challenge::ChallengeManager> {
479    CHALLENGE_MANAGER.get()
480}
481
482// ---------------------------------------------------------------------------
483// Helper: compute unattributed replay thumbprint from proof
484// ---------------------------------------------------------------------------
485
486/// Compute the frozen CDDL §7.1 content-bound unattributed replay namespace.
487/// This bounded structural helper does not verify signatures or grant admission.
488pub fn unattributed_thumbprint(protected_bytes: &[u8]) -> Result<[u8; 32]> {
489    super::thumbprint::unattributed(protected_bytes)
490}
491
492#[cfg(not(target_arch = "wasm32"))]
493fn current_unix_seconds() -> u64 {
494    use std::time::{SystemTime, UNIX_EPOCH};
495    SystemTime::now()
496        .duration_since(UNIX_EPOCH)
497        .map(|d| d.as_secs())
498        .unwrap_or(0)
499}
500
501#[cfg(target_arch = "wasm32")]
502fn current_unix_seconds() -> u64 {
503    0
504}
505
506#[cfg(test)]
507#[allow(clippy::unwrap_used, clippy::expect_used)]
508mod tests {
509    use super::*;
510
511    fn key(thumb: u8, id: u8) -> ProofReplayKey {
512        ProofReplayKey {
513            signer_thumbprint: [thumb; 32],
514            request_id: [id; 16],
515        }
516    }
517
518    fn far_future() -> u64 {
519        current_unix_seconds() + 3_600
520    }
521
522    #[test]
523    fn mediated_queries_are_distinct_bounded_and_not_dispatch_replays() {
524        let store = InMemoryProofReplayStore::single_verifier_instance(2);
525        let query = MediatedQueryReplayKey {
526            signer_thumbprint: [1; 32],
527            request_id: 7,
528            request_nonce: [2; 16],
529            mediator: "registry".into(),
530            resource: "registry:List".into(),
531            operation: "query".into(),
532        };
533        assert_eq!(
534            admit_mediated_query(&store, &query, far_future()),
535            ProofAdmissionResult::Admitted
536        );
537        assert_eq!(
538            admit_mediated_query(&store, &query, far_future()),
539            ProofAdmissionResult::Replayed
540        );
541        let other_resource = MediatedQueryReplayKey {
542            resource: "model:one".into(),
543            ..query.clone()
544        };
545        assert_eq!(
546            admit_mediated_query(&store, &other_resource, far_future()),
547            ProofAdmissionResult::Admitted
548        );
549        let fresh = MediatedQueryReplayKey {
550            request_id: 8,
551            ..query.clone()
552        };
553        assert_eq!(
554            admit_mediated_query(&store, &fresh, far_future()),
555            ProofAdmissionResult::Failed
556        );
557        // Saturation does not evict an accepted record or consume dispatch capacity.
558        assert_eq!(
559            admit_mediated_query(&store, &query, far_future()),
560            ProofAdmissionResult::Replayed
561        );
562        assert_eq!(
563            admit_request_proof(
564                &store,
565                ProofDisposition::Authenticated,
566                &key(1, 7),
567                far_future()
568            ),
569            ProofAdmissionResult::Admitted
570        );
571        let empty = InMemoryProofReplayStore::single_verifier_instance(4);
572        assert_eq!(
573            admit_mediated_query(&empty, &query, current_unix_seconds()),
574            ProofAdmissionResult::Failed
575        );
576        assert_eq!(
577            admit_mediated_query(&empty, &query, far_future()),
578            ProofAdmissionResult::Admitted
579        );
580        let distinct_client_request = MediatedQueryReplayKey {
581            request_nonce: [3; 16],
582            ..query.clone()
583        };
584        assert_eq!(
585            admit_mediated_query(&empty, &distinct_client_request, far_future()),
586            ProofAdmissionResult::Admitted
587        );
588        let oversized = MediatedQueryReplayKey {
589            resource: "x".repeat(4097),
590            ..query
591        };
592        assert_eq!(
593            admit_mediated_query(&empty, &oversized, far_future()),
594            ProofAdmissionResult::Failed
595        );
596    }
597
598    #[test]
599    fn source_credentials_are_consumed_once_in_a_separate_partition() {
600        let store = InMemoryProofReplayStore::single_verifier_instance(2);
601        let credential = CredentialReplayKey {
602            issuer_client_namespace: [7; 32],
603            credential_identity: [8; 32],
604        };
605        assert_eq!(
606            store.check_and_insert_credential(&credential, far_future()),
607            ProofAdmissionResult::Admitted
608        );
609        assert_eq!(
610            store.check_and_insert_credential(&credential, far_future()),
611            ProofAdmissionResult::Replayed
612        );
613        assert_eq!(
614            store.check_and_insert(ProofDisposition::Authenticated, &key(7, 8), far_future()),
615            ProofAdmissionResult::Admitted,
616            "source-token admission must not consume the RPC request-proof key"
617        );
618        assert_eq!(
619            store.check_and_insert_credential(
620                &CredentialReplayKey {
621                    credential_identity: [9; 32],
622                    ..credential
623                },
624                far_future()
625            ),
626            ProofAdmissionResult::Admitted
627        );
628    }
629
630    /// The expiry-ordered reclamation admits a new record once an old one has
631    /// expired, reclaims only expired records (stops at the first live one),
632    /// and never evicts an unexpired record to make room.
633    #[test]
634    fn expiry_map_reclaims_only_expired_records_in_order() {
635        let mut m: ExpiryMap<u64> = ExpiryMap::default();
636        let max = 2;
637        // Two records: one expires at t=100, one is long-lived (t=1000).
638        assert_eq!(m.admit(&1, 100, max, 50), ProofAdmissionResult::Admitted);
639        assert_eq!(m.admit(&2, 1000, max, 50), ProofAdmissionResult::Admitted);
640        // At capacity: a third at t<100 fails closed (nothing expired yet), and
641        // the live records are untouched.
642        assert_eq!(m.admit(&3, 200, max, 60), ProofAdmissionResult::Failed);
643        assert!(m.entries.contains_key(&1));
644        assert!(m.entries.contains_key(&2));
645        // After key 1 expires, its slot is reclaimed and key 3 is admitted;
646        // key 2 (still live) is NOT evicted.
647        assert_eq!(m.admit(&3, 200, max, 150), ProofAdmissionResult::Admitted);
648        assert!(!m.entries.contains_key(&1)); // reclaimed
649        assert!(m.entries.contains_key(&2)); // unexpired, retained
650        assert!(m.entries.contains_key(&3));
651        // gc touched only the one expired record, leaving the live front intact.
652        assert_eq!(m.entries.len(), 2);
653    }
654
655    #[test]
656    fn a_fresh_key_is_admitted_once_and_never_twice() {
657        let store = InMemoryProofReplayStore::single_verifier_instance(16);
658        let k = key(1, 1);
659        assert_eq!(
660            admit_request_proof(&store, ProofDisposition::Authenticated, &k, far_future()),
661            ProofAdmissionResult::Admitted
662        );
663        assert_eq!(
664            admit_request_proof(&store, ProofDisposition::Authenticated, &k, far_future()),
665            ProofAdmissionResult::Replayed
666        );
667    }
668
669    /// The same request_id under a different signer namespace is a different
670    /// request, so the thumbprint must be part of the key.
671    #[test]
672    fn the_signer_namespace_is_part_of_the_key() {
673        let store = InMemoryProofReplayStore::single_verifier_instance(16);
674        assert_eq!(
675            admit_request_proof(
676                &store,
677                ProofDisposition::Authenticated,
678                &key(1, 7),
679                far_future()
680            ),
681            ProofAdmissionResult::Admitted
682        );
683        assert_eq!(
684            admit_request_proof(
685                &store,
686                ProofDisposition::Authenticated,
687                &key(2, 7),
688                far_future()
689            ),
690            ProofAdmissionResult::Admitted
691        );
692    }
693
694    /// Partitions are separate: the same key in the other partition is a
695    /// distinct record, and a saturated unattributed partition can neither
696    /// delay nor deny authenticated admission.
697    #[test]
698    fn partitions_are_independent_and_saturation_does_not_cross() {
699        let store = InMemoryProofReplayStore::single_verifier_instance(2);
700        let k = key(1, 1);
701        assert_eq!(
702            admit_request_proof(&store, ProofDisposition::Unattributed, &k, far_future()),
703            ProofAdmissionResult::Admitted
704        );
705        assert_eq!(
706            admit_request_proof(&store, ProofDisposition::Authenticated, &k, far_future()),
707            ProofAdmissionResult::Admitted
708        );
709
710        // Saturate the unattributed partition.
711        assert_eq!(
712            admit_request_proof(
713                &store,
714                ProofDisposition::Unattributed,
715                &key(1, 2),
716                far_future()
717            ),
718            ProofAdmissionResult::Admitted
719        );
720        assert_eq!(
721            admit_request_proof(
722                &store,
723                ProofDisposition::Unattributed,
724                &key(1, 3),
725                far_future()
726            ),
727            ProofAdmissionResult::Failed
728        );
729
730        // The authenticated partition is unaffected.
731        assert_eq!(
732            admit_request_proof(
733                &store,
734                ProofDisposition::Authenticated,
735                &key(1, 3),
736                far_future()
737            ),
738            ProofAdmissionResult::Admitted
739        );
740    }
741
742    /// Capacity pressure fails closed. It never evicts an unexpired accepted
743    /// record to make room, so an admitted proof can never be re-admitted.
744    #[test]
745    fn capacity_fails_closed_without_evicting_unexpired_records() {
746        let store = InMemoryProofReplayStore::single_verifier_instance(1);
747        let admitted = key(1, 1);
748        assert_eq!(
749            admit_request_proof(
750                &store,
751                ProofDisposition::Authenticated,
752                &admitted,
753                far_future()
754            ),
755            ProofAdmissionResult::Admitted
756        );
757        assert_eq!(
758            admit_request_proof(
759                &store,
760                ProofDisposition::Authenticated,
761                &key(1, 2),
762                far_future()
763            ),
764            ProofAdmissionResult::Failed
765        );
766        // The first record survived the pressure.
767        assert_eq!(
768            admit_request_proof(
769                &store,
770                ProofDisposition::Authenticated,
771                &admitted,
772                far_future()
773            ),
774            ProofAdmissionResult::Replayed
775        );
776    }
777
778    /// Records are collectable once their signed expiry has passed; because
779    /// verification enforces the identical deadline, nothing admissible is
780    /// ever collected.
781    #[test]
782    fn expired_records_are_collected() {
783        let store = InMemoryProofReplayStore::single_verifier_instance(1);
784        let stale = key(1, 1);
785        // Expiry already in the past.
786        assert_eq!(
787            store.check_and_insert(ProofDisposition::Authenticated, &stale, 1),
788            ProofAdmissionResult::Admitted
789        );
790        // A new key can be admitted: the stale record is collected, not evicted.
791        assert_eq!(
792            admit_request_proof(
793                &store,
794                ProofDisposition::Authenticated,
795                &key(1, 2),
796                far_future()
797            ),
798            ProofAdmissionResult::Admitted
799        );
800    }
801
802    // -- domain guarantees --------------------------------------------------
803
804    /// A namespace-affine deployment that routes a request to a node holding
805    /// no history for that namespace MUST deny, not admit.
806    struct AffineStore {
807        owned: [u8; 32],
808        inner: InMemoryProofReplayStore,
809    }
810
811    impl ProofReplayStore for AffineStore {
812        fn domain_guarantee(&self) -> ReplayDomainGuarantee {
813            ReplayDomainGuarantee::NamespaceAffineRouting
814        }
815        fn owns_namespace(&self, signer_thumbprint: &[u8; 32]) -> bool {
816            *signer_thumbprint == self.owned
817        }
818        fn check_and_insert(
819            &self,
820            partition: ProofDisposition,
821            key: &ProofReplayKey,
822            expires_at: u64,
823        ) -> ProofAdmissionResult {
824            self.inner.check_and_insert(partition, key, expires_at)
825        }
826    }
827
828    #[test]
829    fn affine_routing_denies_a_namespace_this_node_does_not_own() {
830        let store = AffineStore {
831            owned: [1u8; 32],
832            inner: InMemoryProofReplayStore::single_verifier_instance(16),
833        };
834        assert_eq!(
835            admit_request_proof(
836                &store,
837                ProofDisposition::Authenticated,
838                &key(1, 1),
839                far_future()
840            ),
841            ProofAdmissionResult::Admitted,
842            "the owned namespace is admitted"
843        );
844        assert_eq!(
845            admit_request_proof(
846                &store,
847                ProofDisposition::Authenticated,
848                &key(2, 1),
849                far_future()
850            ),
851            ProofAdmissionResult::Failed,
852            "failover to a node without this namespace's history must deny"
853        );
854    }
855
856    /// A store whose backend is unavailable reports Failed, and Failed is
857    /// always a denial — it is never treated as "not seen before".
858    #[test]
859    fn an_unavailable_backend_fails_closed() {
860        struct DeadBackend;
861        impl ProofReplayStore for DeadBackend {
862            fn domain_guarantee(&self) -> ReplayDomainGuarantee {
863                ReplayDomainGuarantee::LinearizableSharedStore
864            }
865            fn check_and_insert(
866                &self,
867                _p: ProofDisposition,
868                _k: &ProofReplayKey,
869                _e: u64,
870            ) -> ProofAdmissionResult {
871                ProofAdmissionResult::Failed
872            }
873        }
874        let store = DeadBackend;
875        assert_eq!(
876            admit_request_proof(
877                &store,
878                ProofDisposition::Authenticated,
879                &key(1, 1),
880                far_future()
881            ),
882            ProofAdmissionResult::Failed
883        );
884    }
885
886    // -- single-verifier lease ---------------------------------------------
887
888    /// The lease is exclusive: a second acquisition on the same path — the
889    /// "two replicas both set single-verifier-instance" case — fails, so the
890    /// second verifier cannot install a per-process store under a domain-wide
891    /// guarantee it does not hold.
892    #[test]
893    fn the_single_verifier_lease_is_exclusive() {
894        let path = std::env::temp_dir().join(format!(
895            "hyprstream-replay-lease-{}.lock",
896            std::process::id()
897        ));
898        let _ = std::fs::remove_file(&path);
899
900        let held = SingleVerifierLease::acquire(&path).expect("first acquisition succeeds");
901        assert_eq!(held.path(), path.as_path());
902
903        // A second process (here, a second acquisition of the same path while
904        // the first lock is still held) must fail — this is exactly the
905        // misconfigured-second-replica case.
906        let second = SingleVerifierLease::acquire(&path);
907        assert!(
908            second.is_err(),
909            "a second verifier must not be able to hold the same lease"
910        );
911
912        // Once the first lease drops, the lock is released and the path is
913        // acquirable again (a genuine single-verifier restart).
914        drop(held);
915        assert!(
916            SingleVerifierLease::acquire(&path).is_ok(),
917            "the lease is reacquirable after release"
918        );
919        let _ = std::fs::remove_file(&path);
920    }
921
922    /// A linearizable shared store owns every namespace by construction.
923    #[test]
924    fn a_linearizable_store_owns_every_namespace() {
925        struct Shared(InMemoryProofReplayStore);
926        impl ProofReplayStore for Shared {
927            fn domain_guarantee(&self) -> ReplayDomainGuarantee {
928                ReplayDomainGuarantee::LinearizableSharedStore
929            }
930            fn check_and_insert(
931                &self,
932                p: ProofDisposition,
933                k: &ProofReplayKey,
934                e: u64,
935            ) -> ProofAdmissionResult {
936                self.0.check_and_insert(p, k, e)
937            }
938        }
939        let store = Shared(InMemoryProofReplayStore::single_verifier_instance(16));
940        assert!(store.owns_namespace(&[9u8; 32]));
941        assert_eq!(
942            admit_request_proof(
943                &store,
944                ProofDisposition::Authenticated,
945                &key(9, 1),
946                far_future()
947            ),
948            ProofAdmissionResult::Admitted
949        );
950    }
951}