1use 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
43fn b64(bytes: &[u8]) -> String {
46 URL_SAFE_NO_PAD.encode(bytes)
47}
48
49pub const INTERNAL_WORK_JWT_TYP: &str = "iw+jwt";
51
52pub const INTERNAL_WORK_ISSUER: &str = "hyprstream://model-internal-work";
56
57pub const MAX_LIFETIME_SECS: i64 = 120;
61
62pub const MAX_IAT_SKEW_SECS: i64 = 30;
64
65#[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#[derive(Clone, Debug, Serialize, Deserialize)]
86pub struct InternalWorkClaims {
87 pub iss: String,
88 pub sub: String,
90 pub aud: String,
92 pub tenant: String,
94 pub model: String,
96 pub resource: String,
98 pub operation: String,
100 pub iat: i64,
101 pub exp: i64,
102 pub jti: String,
103 pub cnf: Cnf,
105 #[serde(default, skip_serializing_if = "Option::is_none")]
107 pub owner_did: Option<String>,
108 pub caller: Claims,
111}
112
113impl InternalWorkClaims {
114 #[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#[derive(Clone, Debug)]
131pub struct InternalWorkContext {
132 pub subject: crate::envelope::Subject,
135 pub owner_did: Option<String>,
138 pub resource: String,
140 pub operation: String,
142 pub tenant: String,
144 pub model: String,
146 pub jti: String,
148}
149
150pub 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
169pub 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 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 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
260const DEFAULT_REPLAY_CAPACITY: usize = 10_000;
273
274const MAX_REPLAY_CAPACITY: usize = 100_000_000;
276
277const REPLAY_CAPACITY_ENV: &str = "HYPRSTREAM_INTERNAL_WORK_REPLAY_CAPACITY";
280
281pub 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
294pub 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
305fn 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
332struct ReplayState {
334 by_jti: HashMap<String, i64>,
336 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
351fn 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; }
363 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; }
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
389pub 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 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 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 #[test]
537 fn jti_is_single_use_and_expired_entries_are_reclaimed() {
538 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 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 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 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 assert!(!admit_once_in(&mut state, "new", now + 60, now));
582 assert!(state.by_jti.contains_key("sat-late"));
583 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 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 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 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 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 #[test]
664 fn replay_capacity_once_only_configuration_child() {
665 if std::env::var("HYPRSTREAM_S1_CONFIG_CHILD").is_err() {
666 return; }
668 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}