Skip to main content

hyprstream_rpc/auth/
internal_work.rs

1//! Internal execution work orders for the Model→Inference single-service
2//! boundary (user-approved D5, PR1678).
3//!
4//! Model is the authorization authority for Model-routed operations. Its
5//! pinned, allocated Inference instances are subprocessors: they execute work
6//! only for their owning controller and never form an independent authority
7//! domain. When Model forwards an already-authorized operation to one of its
8//! pinned instances, it mints a short-lived, Model-signed **internal work
9//! token** (`typ: "iw+jwt"`) instead of relaying the caller's credential:
10//!
11//! - the token is bound to the pinned controller key (`cnf.jwk`) and is
12//!   verified against that pinned key — not against the CA key source;
13//! - `aud` names exactly one allocated instance; `tenant`/`model` must match
14//!   that instance's binding;
15//! - `resource`/`operation` pin the exact downstream dispatch coordinate the
16//!   controller already authorized at ingress;
17//! - `exp` is capped by the caller's own expiry and a hard 120 s lifetime;
18//!   `jti` is admitted once per worker process;
19//! - the original caller's verified claims snapshot rides along so
20//!   subject-keyed TTT state, stream ownership, and ledger accounting keep
21//!   attributing to the ORIGINAL caller — never to Model.
22//!
23//! **This token is authority nowhere else.** The generic `verify_claims`
24//! pipeline rejects `iw+jwt` at every service (the trait hook defaults to
25//! deny); only a service operating a pinned execution boundary overrides the
26//! hook. It is never a bearer for Policy, Registry, Discovery, OAI, or any
27//! other control-plane surface, and it is never a substitute for a holder
28//! credential crossing an EXTERNAL boundary.
29
30use std::collections::HashMap;
31use std::sync::OnceLock;
32
33use anyhow::Result;
34use ed25519_dalek::{Signer as _, Verifier as _, VerifyingKey};
35use serde::{Deserialize, Serialize};
36
37use base64::engine::general_purpose::URL_SAFE_NO_PAD;
38use base64::Engine as _;
39
40use super::claims::{Claims, Cnf, CnfJwk};
41use super::jwt::{self, JwkThumbprintInput};
42
43/// URL-safe base64 without padding — the JWT/JWK encoding used by the
44/// existing `Claims`/`cnf` machinery.
45fn b64(bytes: &[u8]) -> String {
46    URL_SAFE_NO_PAD.encode(bytes)
47}
48
49/// JOSE `typ` for internal execution work orders.
50pub const INTERNAL_WORK_JWT_TYP: &str = "iw+jwt";
51
52/// Informational issuer marker. Verification is pinned-key, not issuer-based;
53/// a non-empty issuer deliberately avoids the #328 empty-iss in-process
54/// shortcut so a future subprocess/UDS leg needs no locality exception.
55pub const INTERNAL_WORK_ISSUER: &str = "hyprstream://model-internal-work";
56
57/// Hard upper bound on one work order's lifetime. Model caps `exp` by the
58/// caller's own expiry as well; this bound keeps a leaked token's window
59/// short regardless of the caller credential.
60pub const MAX_LIFETIME_SECS: i64 = 120;
61
62/// Maximum accepted clock skew between mint (`iat`) and admission.
63pub const MAX_IAT_SKEW_SECS: i64 = 30;
64
65/// The exact downstream dispatch coordinate one work order authorizes.
66///
67/// Model mints one token per forwarded operation; the worker's per-method PEP
68/// requires an exact match before executing.
69#[derive(Clone, Debug, PartialEq, Eq)]
70pub struct InternalWorkScope {
71    pub resource: String,
72    pub operation: String,
73}
74
75impl InternalWorkScope {
76    pub fn new(resource: impl Into<String>, operation: impl Into<String>) -> Self {
77        Self {
78            resource: resource.into(),
79            operation: operation.into(),
80        }
81    }
82}
83
84/// Claims of one internal execution work order.
85#[derive(Clone, Debug, Serialize, Deserialize)]
86pub struct InternalWorkClaims {
87    pub iss: String,
88    /// The ORIGINAL caller's verified subject (resolved at Model ingress).
89    pub sub: String,
90    /// The one allocated instance this work order is valid for.
91    pub aud: String,
92    /// The instance's authority-verified tenant.
93    pub tenant: String,
94    /// The instance's model reference.
95    pub model: String,
96    /// Exact downstream resource coordinate (e.g. `inference:generateStream`).
97    pub resource: String,
98    /// Exact downstream operation scope (e.g. `infer`).
99    pub operation: String,
100    pub iat: i64,
101    pub exp: i64,
102    pub jti: String,
103    /// Holder binding: the pinned controller's Ed25519 key.
104    pub cnf: Cnf,
105    /// Original caller's authenticated pairwise DID (ledger attribution).
106    #[serde(default, skip_serializing_if = "Option::is_none")]
107    pub owner_did: Option<String>,
108    /// The caller's verified claims snapshot from Model ingress. The raw
109    /// bearer string is `#[serde(skip)]` on `Claims` and is never embedded.
110    pub caller: Claims,
111}
112
113impl InternalWorkClaims {
114    /// The confirmation JWK for a controller verifying key.
115    #[must_use]
116    pub fn controller_cnf(controller: &VerifyingKey) -> Cnf {
117        Cnf {
118            jwk: Some(CnfJwk {
119                kty: "OKP".to_owned(),
120                crv: "Ed25519".to_owned(),
121                x: b64(controller.as_bytes()),
122            }),
123            jkt: None,
124            hs_signer_suite: None,
125        }
126    }
127}
128
129/// The verified work order installed on an [`crate::service::EnvelopeContext`].
130#[derive(Clone, Debug)]
131pub struct InternalWorkContext {
132    /// Original caller's subject — what subject-keyed state, streams, and
133    /// accounting must attribute to.
134    pub subject: crate::envelope::Subject,
135    /// Original caller's authenticated pairwise DID, when the caller presented
136    /// one (ledger owner attribution).
137    pub owner_did: Option<String>,
138    /// Bound downstream resource coordinate.
139    pub resource: String,
140    /// Bound downstream operation scope.
141    pub operation: String,
142    /// Instance tenant.
143    pub tenant: String,
144    /// Instance model reference.
145    pub model: String,
146    /// Single-use admission id.
147    pub jti: String,
148}
149
150/// Encode and sign a work order (`typ: "iw+jwt"`, pinned Ed25519).
151pub fn encode_internal_work(
152    claims: &InternalWorkClaims,
153    signing_key: &ed25519_dalek::SigningKey,
154) -> String {
155    let kid = jwt::kid_for_key(signing_key);
156    let header = format!(r#"{{"alg":"EdDSA","typ":"{INTERNAL_WORK_JWT_TYP}","kid":"{kid}"}}"#);
157    let header_b64 = b64(header.as_bytes());
158    let payload_json = serde_json::to_string(claims).unwrap_or_else(|_err| {
159        #[cfg(not(target_arch = "wasm32"))]
160        tracing::error!("internal work claims serialization failed: {_err}");
161        "{}".to_owned()
162    });
163    let payload_b64 = b64(payload_json.as_bytes());
164    let signing_input = format!("{header_b64}.{payload_b64}");
165    let signature = signing_key.sign(signing_input.as_bytes());
166    format!("{signing_input}.{}", b64(signature.to_bytes().as_ref()))
167}
168
169/// Verify a work order against the PINNED controller key (never a CA key
170/// source) and bind it to one expected instance audience.
171///
172/// Pinned-alg Ed25519 only; `typ` must be exactly [`INTERNAL_WORK_JWT_TYP`];
173/// the declared `kid` must name the pinned key (invariant I2); freshness and
174/// the hard lifetime bound are enforced here.
175pub fn verify_internal_work(
176    token: &str,
177    controller: &VerifyingKey,
178    expected_aud: &str,
179    now: i64,
180) -> Result<InternalWorkClaims> {
181    let parts: Vec<&str> = token.split('.').collect();
182    anyhow::ensure!(parts.len() == 3, "internal work token is malformed");
183    let header = jwt::parse_protected_header(token)?;
184    anyhow::ensure!(
185        header.typ == INTERNAL_WORK_JWT_TYP,
186        "internal work token has wrong typ {:?}",
187        header.typ
188    );
189    anyhow::ensure!(
190        header.alg == "EdDSA",
191        "internal work token must be pinned EdDSA"
192    );
193    let expected_kid = jwt::jwk_thumbprint(&JwkThumbprintInput::Ed25519 {
194        x: controller.as_bytes(),
195    });
196    anyhow::ensure!(
197        header.kid == expected_kid,
198        "internal work token kid does not name the pinned controller key"
199    );
200    let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
201        .decode(parts[1])
202        .map_err(|e| anyhow::anyhow!("internal work payload decode failed: {e}"))?;
203    let claims: InternalWorkClaims = serde_json::from_slice(&payload)
204        .map_err(|e| anyhow::anyhow!("internal work claims parse failed: {e}"))?;
205    anyhow::ensure!(
206        claims.iss == INTERNAL_WORK_ISSUER,
207        "internal work token issuer is not the internal work authority"
208    );
209    anyhow::ensure!(claims.exp > now, "internal work token is expired");
210    anyhow::ensure!(
211        (now - claims.iat).abs() <= MAX_IAT_SKEW_SECS,
212        "internal work token iat is outside the admission skew window"
213    );
214    anyhow::ensure!(
215        claims.exp - claims.iat <= MAX_LIFETIME_SECS,
216        "internal work token exceeds the maximum internal lifetime"
217    );
218    anyhow::ensure!(
219        claims.aud == expected_aud,
220        "internal work token audience does not name this instance"
221    );
222    anyhow::ensure!(
223        !claims.tenant.is_empty(),
224        "internal work token carries no tenant"
225    );
226    anyhow::ensure!(
227        !claims.model.is_empty(),
228        "internal work token carries no model"
229    );
230    anyhow::ensure!(!claims.jti.is_empty(), "internal work token carries no jti");
231    // Holder binding: the claims must name the pinned controller key itself.
232    anyhow::ensure!(
233        claims
234            .cnf
235            .jwk
236            .as_ref()
237            .is_some_and(|jwk| jwk.x == b64(controller.as_bytes())),
238        "internal work token cnf does not bind the pinned controller key"
239    );
240    // Signature LAST: parse/structure failures are cheaper than verification.
241    let signature: [u8; 64] = base64::engine::general_purpose::URL_SAFE_NO_PAD
242        .decode(parts[2])
243        .map_err(|e| anyhow::anyhow!("internal work signature decode failed: {e}"))?
244        .try_into()
245        .map_err(|_| anyhow::anyhow!("internal work signature has wrong length"))?;
246    let signing_input = format!("{}.{}", parts[0], parts[1]);
247    controller
248        .verify(
249            signing_input.as_bytes(),
250            &ed25519_dalek::Signature::from_bytes(&signature),
251        )
252        .map_err(|_| {
253            anyhow::anyhow!(
254                "internal work token signature does not verify against the pinned controller key"
255            )
256        })?;
257    Ok(claims)
258}
259
260// ── bounded single-use jti admission ────────────────────────────────────────
261//
262// Bot finding 4135785121 (P2, PR-introduced): the original cache was a fixed
263// 10,000-entry `HashMap` with a whole-map `retain` on every admission and
264// fail-closed saturation — capping aggregate steady-state admission near
265// 83/s at a 120 s lifetime. This cache reclaims in EXPIRY ORDER (amortized
266// O(1) per admission: each entry is inserted once and purged once), carries
267// a validated deployment-configurable capacity, and preserves atomic
268// single-use admission under the same mutex. Expired entries are the ONLY
269// ones reclaimed; a cache full of unexpired entries fails closed.
270
271/// Default capacity when the deployment does not configure one.
272const DEFAULT_REPLAY_CAPACITY: usize = 10_000;
273
274/// Upper sanity bound for a configured capacity (reject absurd values).
275const MAX_REPLAY_CAPACITY: usize = 100_000_000;
276
277/// Environment override read once on first cache use. Invalid or zero values
278/// are FAIL-CLOSED: admission denies while the misconfiguration persists.
279const REPLAY_CAPACITY_ENV: &str = "HYPRSTREAM_INTERNAL_WORK_REPLAY_CAPACITY";
280
281/// Validate a requested replay-cache capacity.
282pub fn validate_replay_capacity(capacity: usize) -> Result<usize, String> {
283    if capacity == 0 {
284        Err("internal work replay capacity must be at least 1".to_owned())
285    } else if capacity > MAX_REPLAY_CAPACITY {
286        Err(format!(
287            "internal work replay capacity {capacity} exceeds the sanity bound {MAX_REPLAY_CAPACITY}"
288        ))
289    } else {
290        Ok(capacity)
291    }
292}
293
294/// Configure the deployment replay-cache capacity (validated, once-only —
295/// it must be set before the first admission materializes the cache).
296pub fn configure_internal_work_replay_capacity(capacity: usize) -> Result<(), String> {
297    let validated = validate_replay_capacity(capacity)?;
298    CONFIGURED_CAPACITY
299        .set(validated)
300        .map_err(|_| "internal work replay capacity was already configured".to_owned())
301}
302
303static CONFIGURED_CAPACITY: OnceLock<usize> = OnceLock::new();
304
305/// The effective capacity: explicit configuration, else a validated
306/// environment override, else the default. An invalid environment value
307/// yields 0, which fails every admission closed (see [`admit_once_in`]).
308fn effective_capacity() -> usize {
309    *CONFIGURED_CAPACITY.get_or_init(|| {
310        match std::env::var(REPLAY_CAPACITY_ENV) {
311            Ok(raw) => match raw.trim().parse::<usize>() {
312                Ok(parsed) => validate_replay_capacity(parsed).unwrap_or_else(|e| {
313                    #[cfg(not(target_arch = "wasm32"))]
314                    tracing::error!(
315                        "invalid {REPLAY_CAPACITY_ENV}={raw:?}: {e} — internal work admission FAILS CLOSED"
316                    );
317                    0
318                }),
319                Err(_) => {
320                    #[cfg(not(target_arch = "wasm32"))]
321                    tracing::error!(
322                        "invalid {REPLAY_CAPACITY_ENV}={raw:?}: not a usize — internal work admission FAILS CLOSED"
323                    );
324                    0
325                }
326            },
327            Err(_) => DEFAULT_REPLAY_CAPACITY,
328        }
329    })
330}
331
332/// Bounded single-use replay state with expiry-ordered reclamation.
333struct ReplayState {
334    /// jti -> expiry (authoritative membership).
335    by_jti: HashMap<String, i64>,
336    /// (expiry, jti) — ordered so expired entries reclaim from the front.
337    by_expiry: std::collections::BTreeSet<(i64, String)>,
338    capacity: usize,
339}
340
341impl ReplayState {
342    fn new(capacity: usize) -> Self {
343        Self {
344            by_jti: HashMap::new(),
345            by_expiry: std::collections::BTreeSet::new(),
346            capacity,
347        }
348    }
349}
350
351/// The admission decision over one bounded state (isolated for tests).
352///
353/// Order of operations is the SECURITY contract: purge expired first, then
354/// duplicate check, then saturation check. Expired entries are the only ones
355/// reclaimed; a cache whose capacity is entirely unexpired entries fails
356/// closed. The caller holds the lock across the whole decision, so
357/// check-and-insert is atomic (exactly-once under concurrency).
358fn admit_once_in(state: &mut ReplayState, jti: &str, exp: i64, now: i64) -> bool {
359    let capacity = state.capacity;
360    if capacity == 0 {
361        return false; // invalid/unsized configuration: fail closed
362    }
363    // Expiry-ordered reclamation: every entry with exp <= now leaves, front
364    // first. Amortized O(1): an entry is purged at most once.
365    while let Some(front) = state.by_expiry.first().cloned() {
366        let (entry_exp, entry_jti) = &front;
367        if entry_exp > &now {
368            break;
369        }
370        state.by_expiry.remove(&front);
371        state.by_jti.remove(entry_jti);
372    }
373    if state.by_jti.contains_key(jti) {
374        return false;
375    }
376    if state.by_jti.len() >= capacity {
377        return false; // full of UNEXPIRED entries: fail closed, never evict
378    }
379    state.by_jti.insert(jti.to_owned(), exp);
380    state.by_expiry.insert((exp, jti.to_owned()));
381    true
382}
383
384fn jti_cache() -> &'static parking_lot::Mutex<ReplayState> {
385    static CACHE: OnceLock<parking_lot::Mutex<ReplayState>> = OnceLock::new();
386    CACHE.get_or_init(|| parking_lot::Mutex::new(ReplayState::new(effective_capacity())))
387}
388
389/// Admit a work-order `jti` exactly once. Entries expire at the token's own
390/// `exp`; the cache reclaims in expiry order, is capacity-bounded
391/// (deployment-configurable), and fails closed when full of unexpired
392/// entries or misconfigured. This is worker-local defense in depth ON TOP of
393/// the envelope replay gates, not a replacement for them.
394pub fn admit_internal_work_jti_once(jti: &str, exp: i64, now: i64) -> bool {
395    let mut cache = jti_cache().lock();
396    admit_once_in(&mut cache, jti, exp, now)
397}
398
399#[cfg(test)]
400#[allow(clippy::unwrap_used, clippy::expect_used)]
401mod tests {
402    use super::*;
403    use ed25519_dalek::SigningKey;
404
405    fn controller() -> SigningKey {
406        SigningKey::from_bytes(&[0xA5; 32])
407    }
408
409    fn fixture_claims(signer: &SigningKey, now: i64) -> InternalWorkClaims {
410        InternalWorkClaims {
411            iss: INTERNAL_WORK_ISSUER.to_owned(),
412            sub: "alice".to_owned(),
413            aud: "inference-fixture01".to_owned(),
414            tenant: "tenant-a".to_owned(),
415            model: "qwen3:main".to_owned(),
416            resource: "inference:generateStream".to_owned(),
417            operation: "infer".to_owned(),
418            iat: now,
419            exp: now + 60,
420            jti: "jti-1".to_owned(),
421            cnf: InternalWorkClaims::controller_cnf(&signer.verifying_key()),
422            owner_did: Some("did:key:z6Mk".to_owned()),
423            caller: Claims::new("alice".to_owned(), now, now + 3600)
424                .with_tenant("tenant-a".to_owned()),
425        }
426    }
427
428    #[test]
429    fn mint_verify_round_trip_binds_instance_and_controller() {
430        let signer = controller();
431        let now = chrono::Utc::now().timestamp();
432        let claims = fixture_claims(&signer, now);
433        let token = encode_internal_work(&claims, &signer);
434        let verified = verify_internal_work(&token, &signer.verifying_key(), &claims.aud, now)
435            .expect("a well-formed work order must verify against its pinned controller");
436        assert_eq!(verified.sub, "alice");
437        assert_eq!(verified.tenant, "tenant-a");
438        assert_eq!(verified.model, "qwen3:main");
439        assert_eq!(verified.resource, "inference:generateStream");
440        assert_eq!(verified.operation, "infer");
441        assert_eq!(verified.owner_did.as_deref(), Some("did:key:z6Mk"));
442        assert_eq!(verified.caller.sub, "alice");
443        assert!(
444            verified.caller.token.is_none(),
445            "the caller snapshot must never embed the raw bearer"
446        );
447    }
448
449    #[test]
450    fn foreign_signer_never_verifies() {
451        let signer = controller();
452        let attacker = SigningKey::from_bytes(&[0xA6; 32]);
453        let now = chrono::Utc::now().timestamp();
454        let token = encode_internal_work(&fixture_claims(&signer, now), &attacker);
455        let err = verify_internal_work(&token, &signer.verifying_key(), "inference-fixture01", now)
456            .expect_err("a foreign key cannot mint for a pinned controller");
457        assert!(err.to_string().contains("pinned controller key"), "{err:#}");
458    }
459
460    #[test]
461    fn wrong_audience_tenant_or_model_denies() {
462        let signer = controller();
463        let now = chrono::Utc::now().timestamp();
464        let token = encode_internal_work(&fixture_claims(&signer, now), &signer);
465        let err = verify_internal_work(&token, &signer.verifying_key(), "inference-other", now)
466            .expect_err("a work order for another instance must deny");
467        assert!(err.to_string().contains("audience"), "{err:#}");
468        let claims = fixture_claims(&signer, now);
469        let mut other_instance = claims.clone();
470        other_instance.tenant = "tenant-b".to_owned();
471        let token2 = encode_internal_work(&other_instance, &signer);
472        // The tenant/model mismatch is adjudicated by the worker against its
473        // own binding; verification returns the claims so the adapter can
474        // fail closed. Assert the values arrive un-tampered (signature holds).
475        let verified = verify_internal_work(&token2, &signer.verifying_key(), &claims.aud, now)
476            .expect("signature remains valid for a different tenant binding");
477        assert_eq!(verified.tenant, "tenant-b");
478    }
479
480    #[test]
481    fn expired_future_iat_and_oversized_lifetime_denies() {
482        let signer = controller();
483        let now = chrono::Utc::now().timestamp();
484
485        let mut expired = fixture_claims(&signer, now);
486        expired.exp = now - 1;
487        let token = encode_internal_work(&expired, &signer);
488        let err = verify_internal_work(&token, &signer.verifying_key(), &expired.aud, now)
489            .expect_err("expired work orders must deny");
490        assert!(err.to_string().contains("expired"), "{err:#}");
491
492        let mut future = fixture_claims(&signer, now);
493        future.iat = now + MAX_IAT_SKEW_SECS + 1;
494        let token = encode_internal_work(&future, &signer);
495        let err = verify_internal_work(&token, &signer.verifying_key(), &future.aud, now)
496            .expect_err("future-minted work orders must deny");
497        assert!(err.to_string().contains("skew"), "{err:#}");
498
499        let mut long = fixture_claims(&signer, now);
500        long.exp = now + MAX_LIFETIME_SECS + 1;
501        let token = encode_internal_work(&long, &signer);
502        let err = verify_internal_work(&token, &signer.verifying_key(), &long.aud, now)
503            .expect_err("oversized lifetimes must deny");
504        assert!(
505            err.to_string().contains("maximum internal lifetime"),
506            "{err:#}"
507        );
508    }
509
510    #[test]
511    fn wrong_typ_or_alg_denies() {
512        let signer = controller();
513        let now = chrono::Utc::now().timestamp();
514        let claims = fixture_claims(&signer, now);
515        let kid = jwt::kid_for_key(&signer);
516        // at+jwt framing must never be admitted as internal work.
517        let claims_json = serde_json::to_string(&claims).unwrap();
518        let header = format!(r#"{{"alg":"EdDSA","typ":"at+jwt","kid":"{kid}"}}"#);
519        let signing_input = format!("{}.{}", b64(header.as_bytes()), b64(claims_json.as_bytes()));
520        let sig = signer.sign(signing_input.as_bytes());
521        let at_jwt = format!("{signing_input}.{}", b64(sig.to_bytes().as_ref()));
522        let err = verify_internal_work(&at_jwt, &signer.verifying_key(), &claims.aud, now)
523            .expect_err("an at+jwt framing is not an internal work order");
524        assert!(err.to_string().contains("typ"), "{err:#}");
525    }
526
527    // K3 B1 (4064c6bf review): tests that would touch the PROCESS-GLOBAL
528    // replay cache or its capacity OnceLock are isolated — either on a private
529    // ReplayState serialized exactly like the global path (one mutex held
530    // across check-and-insert), or in a forked child process for the
531    // once-only configuration assertion. A sibling's forged future `now` must
532    // not be able to purge another test's in-flight admission, and one test's
533    // OnceLock write must not make another's once-only configure fail.
534    // Assertions themselves are unchanged.
535
536    #[test]
537    fn jti_is_single_use_and_expired_entries_are_reclaimed() {
538        // Isolated state: sibling tests sharing the global cache (or forging
539        // clock values) cannot purge these entries mid-test.
540        let mut state = ReplayState::new(8);
541        let now = chrono::Utc::now().timestamp();
542        let id = "jti-single-use".to_owned();
543        assert!(admit_once_in(&mut state, &id, now + 60, now));
544        assert!(
545            !admit_once_in(&mut state, &id, now + 60, now),
546            "replay must deny"
547        );
548        // Past its exp the entry is reclaimed, so a fresh order with the same
549        // id (impossible for a real mint, but proves the release) admits again.
550        assert!(admit_once_in(&mut state, &id, now + 120, now + 61));
551    }
552
553    #[test]
554    fn jti_saturation_of_unexpired_entries_fails_closed_without_eviction() {
555        let mut state = ReplayState::new(4);
556        let now = chrono::Utc::now().timestamp();
557        for i in 0..4 {
558            assert!(
559                admit_once_in(&mut state, &format!("sat-{i}"), now + 600, now),
560                "fill up to capacity"
561            );
562        }
563        // Full of UNEXPIRED entries: admission denies and nothing is evicted.
564        assert!(!admit_once_in(&mut state, "overflow", now + 600, now));
565        assert_eq!(state.by_jti.len(), 4);
566        assert!(
567            state.by_jti.contains_key("sat-0"),
568            "unexpired entry retained"
569        );
570    }
571
572    #[test]
573    fn jti_reclamation_is_expiry_ordered_and_never_evicts_unexpired() {
574        // Insert OUT of expiry order: sat-late (furthest) first, sat-early last.
575        let mut state = ReplayState::new(2);
576        let now = chrono::Utc::now().timestamp();
577        assert!(admit_once_in(&mut state, "sat-late", now + 600, now));
578        assert!(admit_once_in(&mut state, "sat-early", now + 60, now));
579        assert_eq!(state.by_jti.len(), 2, "capacity reached");
580        // Nothing is expired yet: a new admission fails closed, unexpired kept.
581        assert!(!admit_once_in(&mut state, "new", now + 60, now));
582        assert!(state.by_jti.contains_key("sat-late"));
583        // Advance past ONLY the earliest expiry: exactly it is reclaimed and
584        // the admission succeeds — order comes from expiry, not insertion.
585        assert!(admit_once_in(&mut state, "new", now + 60, now + 61));
586        assert!(
587            !state.by_jti.contains_key("sat-early"),
588            "expired entry reclaimed"
589        );
590        assert!(
591            state.by_jti.contains_key("sat-late"),
592            "unexpired entry never evicted"
593        );
594        assert!(state.by_jti.contains_key("new"));
595    }
596
597    #[test]
598    fn jti_concurrent_duplicate_admission_is_exactly_once() {
599        // The admission path holds ONE mutex across check-and-insert (the
600        // global wrapper does; this isolated fixture serializes identically),
601        // so racing duplicates must yield exactly one admission. The state is
602        // private to this test: no sibling test can purge its in-flight
603        // entries with a forged clock (K3 B1b).
604        let state = parking_lot::Mutex::new(ReplayState::new(64));
605        let state = std::sync::Arc::new(state);
606        let now = chrono::Utc::now().timestamp();
607        let id = format!(
608            "jti-concurrent-{}",
609            std::time::SystemTime::now()
610                .duration_since(std::time::UNIX_EPOCH)
611                .unwrap()
612                .as_nanos()
613        );
614        let exp = now + 600;
615        let handles: Vec<_> = (0..8)
616            .map(|_| {
617                let state = std::sync::Arc::clone(&state);
618                let id = id.clone();
619                std::thread::spawn(move || {
620                    // Same shape as admit_internal_work_jti_once: the mutex is
621                    // held across check-and-insert (atomic exactly-once).
622                    let mut guard = state.lock();
623                    admit_once_in(&mut guard, &id, exp, now)
624                })
625            })
626            .collect();
627        let successes = handles
628            .into_iter()
629            .map(|handle| handle.join().expect("admission thread"))
630            .filter(|admitted| *admitted)
631            .count();
632        assert_eq!(successes, 1, "exactly one racing admission may win");
633        assert_eq!(
634            state.lock().by_jti.len(),
635            1,
636            "the winning admission is the only entry"
637        );
638    }
639
640    #[test]
641    fn replay_capacity_validation_and_zero_capacity_fail_closed() {
642        // Validation: zero and absurd caps are invalid.
643        assert!(validate_replay_capacity(0).is_err());
644        assert!(validate_replay_capacity(MAX_REPLAY_CAPACITY + 1).is_err());
645        assert_eq!(validate_replay_capacity(1).unwrap(), 1);
646        assert_eq!(
647            validate_replay_capacity(MAX_REPLAY_CAPACITY).unwrap(),
648            MAX_REPLAY_CAPACITY
649        );
650        // A zero-capacity state is fail-closed: no admission, no eviction.
651        let mut state = ReplayState::new(0);
652        let now = chrono::Utc::now().timestamp();
653        assert!(!admit_once_in(&mut state, "any", now + 60, now));
654        assert!(state.by_jti.is_empty());
655    }
656
657    /// K3 B1a: the once-only `configure_internal_work_replay_capacity`
658    /// assertion mutates the process-global OnceLock, so it runs in a forked
659    /// child test process where the lock is fresh (same pattern as the
660    /// inference drain child tests). The parent only verifies the child's
661    /// exit status — no assertion is weakened, both configure outcomes are
662    /// still asserted in the child.
663    #[test]
664    fn replay_capacity_once_only_configuration_child() {
665        if std::env::var("HYPRSTREAM_S1_CONFIG_CHILD").is_err() {
666            return; // parent run: only the child below exercises this body
667        }
668        // Fresh process: the OnceLock is unconfigured, so the first validated
669        // call must succeed and the second must be refused.
670        assert!(configure_internal_work_replay_capacity(DEFAULT_REPLAY_CAPACITY).is_ok());
671        assert!(configure_internal_work_replay_capacity(1).is_err());
672        assert_eq!(
673            *CONFIGURED_CAPACITY.get().expect("configured in child"),
674            DEFAULT_REPLAY_CAPACITY
675        );
676    }
677
678    #[test]
679    fn replay_capacity_once_only_configuration_is_child_process_isolated() {
680        let executable = std::env::current_exe().expect("test executable");
681        let mut child = std::process::Command::new(executable)
682            .args([
683                "--exact",
684                "auth::internal_work::tests::replay_capacity_once_only_configuration_child",
685                "--nocapture",
686            ])
687            .env("HYPRSTREAM_S1_CONFIG_CHILD", "1")
688            .stdout(std::process::Stdio::piped())
689            .stderr(std::process::Stdio::piped())
690            .spawn()
691            .expect("spawn config child");
692        let status = child.wait().expect("child wait");
693        assert!(
694            status.success(),
695            "once-only configuration child must pass: {status}"
696        );
697    }
698}