1use std::collections::BTreeSet;
28use std::sync::Arc;
29
30use anyhow::anyhow;
31use parking_lot::RwLock;
32
33#[cfg(test)]
34use crate::identity::Did;
35use crate::registry::SocketKind;
36#[cfg(test)]
37use crate::rpc_client::{CallOptions, RpcClient};
38#[cfg(test)]
39use crate::stream_consumer::StreamHandle;
40use crate::transport::{EndpointType, TransportConfig};
41#[cfg(test)]
42use crate::VerifyingKey;
43
44#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct ServiceQuery {
47 pub service_name: String,
48 pub required_capabilities: BTreeSet<String>,
49 pub profile: ResolverProfile,
50 pub max_attempts: usize,
51}
52
53impl ServiceQuery {
54 pub fn network(service_name: impl Into<String>) -> anyhow::Result<Self> {
55 Self::new(
56 service_name,
57 ["hyprstream-rpc/1".to_owned()],
58 ResolverProfile::NativeIrohRequired,
59 3,
60 )
61 }
62
63 pub fn network_moq(service_name: impl Into<String>) -> anyhow::Result<Self> {
65 Self::new(
66 service_name,
67 ["hyprstream-moq/1".to_owned()],
68 ResolverProfile::NativeIrohRequired,
69 3,
70 )
71 }
72
73 pub fn browser(service_name: impl Into<String>) -> anyhow::Result<Self> {
76 Self::new(
77 service_name,
78 ["hyprstream-rpc/1".to_owned()],
79 ResolverProfile::BrowserWebTransport,
80 1,
81 )
82 }
83
84 pub fn new(
85 service_name: impl Into<String>,
86 capabilities: impl IntoIterator<Item = String>,
87 profile: ResolverProfile,
88 max_attempts: usize,
89 ) -> anyhow::Result<Self> {
90 let service_name = canonical_service_name(&service_name.into())?;
91 anyhow::ensure!(max_attempts > 0, "resolution max_attempts must be non-zero");
92 Ok(Self {
93 service_name,
94 required_capabilities: capabilities.into_iter().collect(),
95 profile,
96 max_attempts: max_attempts.min(16),
97 })
98 }
99}
100
101#[derive(Debug, Clone, PartialEq, Eq)]
106#[cfg(test)]
107pub struct AcceptedStateEvidence {
108 pub service_did: Did,
109 pub digest: [u8; 64],
110 pub epoch: u64,
111 pub expires_at_unix_ms: i64,
112 pub response_ed25519: [u8; 32],
113 pub response_ml_dsa65: Vec<u8>,
114}
115
116#[derive(Debug, Clone, PartialEq, Eq)]
118#[cfg(test)]
119pub struct AnchoredKemRecipient {
120 pub key_id: String,
121 pub recipient: crate::crypto::hybrid_kem::RecipientPublic,
122 pub not_after_unix_ms: i64,
123}
124
125#[derive(Debug, Clone, PartialEq, Eq)]
127#[cfg(test)]
128pub struct ServiceCandidate {
129 pub service_name: String,
130 pub service_did: Did,
131 pub response_verifying_key: [u8; 32],
132 pub response_ml_dsa65: Vec<u8>,
133 pub response_key_id: String,
134 pub request_kem_recipient: Option<AnchoredKemRecipient>,
135 pub transport: TransportConfig,
136 pub capabilities: BTreeSet<String>,
137 pub accepted_state: AcceptedStateEvidence,
138 pub source_signer: [u8; 32],
139 pub expires_at_unix_ms: i64,
140}
141
142#[derive(Debug, Clone, PartialEq, Eq)]
144#[cfg(test)]
145pub struct CandidateDecision {
146 pub candidate_fingerprint: String,
147 pub accepted: bool,
148 pub reason: String,
149}
150
151#[derive(Debug, Clone, PartialEq, Eq)]
153#[cfg(test)]
154pub struct ResolutionEvidence {
155 pub accepted_state_digest: [u8; 64],
156 pub accepted_state_epoch: u64,
157 pub selected_fingerprint: String,
158 pub ordered_decisions: Vec<CandidateDecision>,
159}
160
161#[derive(Debug, Clone)]
163#[cfg(test)]
164pub struct SelectedService {
165 service_name: String,
166 service_did: Did,
167 response_verifying_key: VerifyingKey,
168 response_ml_dsa65: Vec<u8>,
169 response_key_id: String,
170 request_kem_recipient: AnchoredKemRecipient,
171 transport: TransportConfig,
172 capabilities: BTreeSet<String>,
173 expires_at_unix_ms: i64,
174 evidence: ResolutionEvidence,
175}
176
177#[cfg(test)]
178impl SelectedService {
179 pub fn same_authority(&self, other: &Self) -> bool {
180 self.service_name == other.service_name
181 && self.service_did == other.service_did
182 && self.response_verifying_key == other.response_verifying_key
183 && self.response_ml_dsa65 == other.response_ml_dsa65
184 && self.response_key_id == other.response_key_id
185 && self.request_kem_recipient == other.request_kem_recipient
186 && self.evidence.accepted_state_digest == other.evidence.accepted_state_digest
187 && self.evidence.accepted_state_epoch == other.evidence.accepted_state_epoch
188 }
189 pub fn service_name(&self) -> &str {
190 &self.service_name
191 }
192
193 pub fn service_did(&self) -> &Did {
194 &self.service_did
195 }
196
197 pub fn response_verifying_key(&self) -> VerifyingKey {
198 self.response_verifying_key
199 }
200
201 pub fn response_ml_dsa65(&self) -> &[u8] {
202 &self.response_ml_dsa65
203 }
204
205 pub fn response_key_id(&self) -> &str {
206 &self.response_key_id
207 }
208
209 pub fn request_kem_recipient(&self) -> &AnchoredKemRecipient {
210 &self.request_kem_recipient
211 }
212
213 pub fn transport(&self) -> &TransportConfig {
214 &self.transport
215 }
216
217 pub fn capabilities(&self) -> &BTreeSet<String> {
218 &self.capabilities
219 }
220
221 pub fn evidence(&self) -> &ResolutionEvidence {
222 &self.evidence
223 }
224
225 pub fn ensure_fresh(&self, now_unix_ms: i64) -> anyhow::Result<()> {
227 anyhow::ensure!(
228 now_unix_ms < self.expires_at_unix_ms,
229 "resolved service snapshot expired; re-resolution required"
230 );
231 anyhow::ensure!(
232 now_unix_ms < self.request_kem_recipient.not_after_unix_ms,
233 "resolved request KEM recipient expired; re-resolution required"
234 );
235 Ok(())
236 }
237
238 pub fn crypto_stores(
241 &self,
242 ) -> anyhow::Result<(
243 Arc<dyn crate::crypto::hybrid_kem::KemTrustStore>,
244 Arc<dyn crate::envelope::PqTrustStore>,
245 )> {
246 let ed = self.response_verifying_key.to_bytes();
247 let mut kem = crate::crypto::hybrid_kem::KeyedKemTrustStore::new();
248 kem.bind(ed, self.request_kem_recipient.recipient.clone());
249 let pq_key = crate::crypto::pq::ml_dsa_vk_from_bytes(&self.response_ml_dsa65)
250 .map_err(|e| anyhow!("invalid resolved ML-DSA-65 response key: {e}"))?;
251 let mut pq = crate::envelope::KeyedPqTrustStore::new();
252 pq.bind(ed, &pq_key);
253 Ok((Arc::new(kem), Arc::new(pq)))
254 }
255}
256
257#[async_trait::async_trait]
259#[cfg(test)]
260pub trait ServiceResolver: Send + Sync {
261 async fn resolve_service(&self, query: ServiceQuery) -> anyhow::Result<SelectedService>;
262
263 async fn resolve_service_candidates(
266 &self,
267 query: ServiceQuery,
268 ) -> anyhow::Result<Vec<SelectedService>> {
269 Ok(vec![self.resolve_service(query).await?])
270 }
271
272 async fn ensure_current(&self, resolved: &SelectedService) -> anyhow::Result<()>;
275}
276
277#[cfg(test)]
283pub struct ResolvedRpcClient {
284 service_name: String,
285 signing_key: crate::crypto::SigningKey,
286 token: Option<String>,
287 resolver: Arc<dyn ServiceResolver>,
288 request_id: std::sync::atomic::AtomicU64,
289}
290
291#[cfg(test)]
292impl ResolvedRpcClient {
293 pub fn new(
294 service_name: impl Into<String>,
295 signing_key: crate::crypto::SigningKey,
296 token: Option<String>,
297 resolver: Arc<dyn ServiceResolver>,
298 ) -> anyhow::Result<Self> {
299 let service_name = canonical_service_name(&service_name.into())?;
300 Ok(Self {
301 service_name,
302 signing_key,
303 token,
304 resolver,
305 request_id: std::sync::atomic::AtomicU64::new(1),
306 })
307 }
308
309 async fn snapshots(&self) -> anyhow::Result<Vec<SelectedService>> {
310 let query = ServiceQuery::network(self.service_name.clone())?;
311 let max_attempts = query.max_attempts;
312 let resolved = self.resolver.resolve_service_candidates(query).await?;
313 anyhow::ensure!(
314 !resolved.is_empty(),
315 "resolver returned no validated alternatives"
316 );
317 let authority = &resolved[0];
318 anyhow::ensure!(
319 resolved.iter().all(|item| item.same_authority(authority)),
320 "resolver retry set crosses service authority"
321 );
322 Ok(resolved.into_iter().take(max_attempts).collect())
323 }
324
325 fn client_for(&self, snapshot: &SelectedService) -> anyhow::Result<Arc<dyn RpcClient>> {
326 let (kem, pq) = snapshot.crypto_stores()?;
327 let signer = crate::signer::LocalSigner::new(self.signing_key.clone());
328 crate::dial::dial_with_crypto_stores(
329 snapshot.transport(),
330 signer,
331 Some(snapshot.response_verifying_key()),
332 self.token.clone(),
333 Some(kem),
334 Some(pq),
335 )
336 }
337
338 async fn attempt<T, F, Fut>(&self, mut call: F) -> anyhow::Result<T>
339 where
340 F: FnMut(Arc<dyn RpcClient>) -> Fut,
341 Fut: std::future::Future<Output = anyhow::Result<T>>,
342 {
343 for refresh in 0..2 {
344 let mut last_transport_error = None;
345 let mut invalidated = None;
346 for snapshot in self.snapshots().await? {
347 if let Err(error) = self.resolver.ensure_current(&snapshot).await {
348 invalidated = Some(error);
349 break;
350 }
351 let client = self.client_for(&snapshot)?;
352 match call(client).await {
353 Ok(value) => return Ok(value),
354 Err(error)
355 if crate::transport_traits::is_pre_dispatch_transport_error(&error) =>
356 {
357 last_transport_error = Some(error);
358 }
359 Err(error) => return Err(error),
360 }
361 }
362 if let Some(error) = invalidated {
363 if refresh == 0 {
364 continue;
365 }
366 return Err(anyhow!(
367 "resolved service remained invalid after re-resolution: {error}"
368 ));
369 }
370 return Err(last_transport_error
371 .unwrap_or_else(|| anyhow!("validated same-authority alternatives exhausted")));
372 }
373 unreachable!("bounded re-resolution loop always returns")
374 }
375}
376
377#[async_trait::async_trait]
378#[cfg(test)]
379impl RpcClient for ResolvedRpcClient {
380 async fn call(&self, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
381 self.attempt(|c| {
382 let p = payload.clone();
383 async move { c.call(p).await }
384 })
385 .await
386 }
387 async fn call_for_service(&self, service: &str, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
388 anyhow::ensure!(
389 service == self.service_name,
390 "generated service authority mismatch"
391 );
392 let service = service.to_owned();
393 self.attempt(|c| {
394 let p = payload.clone();
395 let s = service.clone();
396 async move { c.call_for_service(&s, p).await }
397 })
398 .await
399 }
400 async fn call_for_service_with_method(
401 &self,
402 service: &str,
403 method_discriminator: u16,
404 payload: Vec<u8>,
405 ) -> anyhow::Result<Vec<u8>> {
406 anyhow::ensure!(
407 service == self.service_name,
408 "generated service authority mismatch"
409 );
410 let service = service.to_owned();
411 self.attempt(|c| {
412 let p = payload.clone();
413 let s = service.clone();
414 async move {
415 c.call_for_service_with_method(&s, method_discriminator, p)
416 .await
417 }
418 })
419 .await
420 }
421 async fn call_with_options(
422 &self,
423 payload: Vec<u8>,
424 options: CallOptions,
425 ) -> anyhow::Result<Vec<u8>> {
426 self.attempt(|c| {
427 let p = payload.clone();
428 let o = options.clone();
429 async move { c.call_with_options(p, o).await }
430 })
431 .await
432 }
433 async fn call_with_options_for_service(
434 &self,
435 service: &str,
436 payload: Vec<u8>,
437 options: CallOptions,
438 ) -> anyhow::Result<Vec<u8>> {
439 anyhow::ensure!(
440 service == self.service_name,
441 "generated service authority mismatch"
442 );
443 let service = service.to_owned();
444 self.attempt(|c| {
445 let p = payload.clone();
446 let o = options.clone();
447 let s = service.clone();
448 async move { c.call_with_options_for_service(&s, p, o).await }
449 })
450 .await
451 }
452
453 async fn call_with_options_for_service_with_method(
454 &self,
455 service: &str,
456 method_discriminator: u16,
457 payload: Vec<u8>,
458 options: CallOptions,
459 ) -> anyhow::Result<Vec<u8>> {
460 anyhow::ensure!(
461 service == self.service_name,
462 "generated service authority mismatch"
463 );
464 let service = service.to_owned();
465 self.attempt(|client| {
466 let payload = payload.clone();
467 let options = options.clone();
468 let service = service.clone();
469 async move {
470 client
471 .call_with_options_for_service_with_method(
472 &service,
473 method_discriminator,
474 payload,
475 options,
476 )
477 .await
478 }
479 })
480 .await
481 }
482
483 async fn call_streaming(
484 &self,
485 payload: Vec<u8>,
486 ephemeral: [u8; 32],
487 ) -> anyhow::Result<Vec<u8>> {
488 self.attempt(|c| {
489 let p = payload.clone();
490 async move { c.call_streaming(p, ephemeral).await }
491 })
492 .await
493 }
494 async fn call_streaming_for_service(
495 &self,
496 service: &str,
497 payload: Vec<u8>,
498 ephemeral: [u8; 32],
499 ) -> anyhow::Result<Vec<u8>> {
500 anyhow::ensure!(
501 service == self.service_name,
502 "generated service authority mismatch"
503 );
504 let service = service.to_owned();
505 self.attempt(|c| {
506 let p = payload.clone();
507 let s = service.clone();
508 async move { c.call_streaming_for_service(&s, p, ephemeral).await }
509 })
510 .await
511 }
512 async fn call_streaming_for_service_with_method(
513 &self,
514 service: &str,
515 method_discriminator: u16,
516 payload: Vec<u8>,
517 ephemeral: [u8; 32],
518 ) -> anyhow::Result<Vec<u8>> {
519 anyhow::ensure!(
520 service == self.service_name,
521 "generated service authority mismatch"
522 );
523 let service = service.to_owned();
524 self.attempt(|c| {
525 let p = payload.clone();
526 let s = service.clone();
527 async move {
528 c.call_streaming_for_service_with_method(&s, method_discriminator, p, ephemeral)
529 .await
530 }
531 })
532 .await
533 }
534 async fn open_stream(&self, payload: Vec<u8>) -> anyhow::Result<Box<dyn StreamHandle>> {
535 self.attempt(|c| {
536 let p = payload.clone();
537 async move { c.open_stream(p).await }
538 })
539 .await
540 }
541 async fn open_stream_from_info(
542 &self,
543 info: crate::stream_info::StreamInfo,
544 secret: [u8; 32],
545 public: [u8; 32],
546 ) -> anyhow::Result<Box<dyn StreamHandle>> {
547 self.attempt(|c| {
548 let i = info.clone();
549 async move { c.open_stream_from_info(i, secret, public).await }
550 })
551 .await
552 }
553 fn next_id(&self) -> u64 {
554 self.request_id
555 .fetch_add(1, std::sync::atomic::Ordering::Relaxed)
556 }
557}
558
559fn canonical_service_name(name: &str) -> anyhow::Result<String> {
560 let canonical = name.trim().to_ascii_lowercase();
561 anyhow::ensure!(!canonical.is_empty(), "service name is empty");
562 anyhow::ensure!(
563 canonical
564 .bytes()
565 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-'),
566 "service name contains non-canonical characters"
567 );
568 anyhow::ensure!(canonical == name, "service name is not canonical");
569 Ok(canonical)
570}
571
572#[cfg(test)]
573fn network_reach(transport: &TransportConfig) -> bool {
574 matches!(
575 transport.endpoint,
576 EndpointType::Quic { .. } | EndpointType::Iroh { .. }
577 )
578}
579
580#[cfg(test)]
581fn native_iroh_reach(transport: &TransportConfig) -> bool {
582 matches!(transport.endpoint, EndpointType::Iroh { .. })
583}
584
585#[cfg(test)]
586fn browser_webtransport_reach(transport: &TransportConfig) -> bool {
587 matches!(transport.endpoint, EndpointType::Quic { .. })
588}
589
590#[cfg(test)]
591fn transport_fingerprint(transport: &TransportConfig) -> String {
592 let bytes = format!("{transport:?}");
593 blake3::hash(bytes.as_bytes()).to_hex().to_string()
594}
595
596#[cfg(test)]
597fn hash_framed(hasher: &mut blake3::Hasher, bytes: &[u8]) {
598 hasher.update(&(bytes.len() as u64).to_be_bytes());
599 hasher.update(bytes);
600}
601
602#[cfg(test)]
603fn candidate_fingerprint(candidate: &ServiceCandidate) -> String {
604 let mut h = blake3::Hasher::new();
605 hash_framed(&mut h, candidate.service_name.as_bytes());
606 hash_framed(&mut h, candidate.service_did.as_str().as_bytes());
607 h.update(&candidate.response_verifying_key);
608 hash_framed(&mut h, &candidate.response_ml_dsa65);
609 hash_framed(&mut h, candidate.response_key_id.as_bytes());
610 if let Some(kem) = &candidate.request_kem_recipient {
611 hash_framed(&mut h, kem.key_id.as_bytes());
612 hash_framed(&mut h, &kem.recipient.encode());
613 }
614 hash_framed(
615 &mut h,
616 transport_fingerprint(&candidate.transport).as_bytes(),
617 );
618 for capability in &candidate.capabilities {
619 hash_framed(&mut h, capability.as_bytes());
620 }
621 h.update(&candidate.accepted_state.digest);
622 h.update(&candidate.accepted_state.epoch.to_be_bytes());
623 hash_framed(
624 &mut h,
625 candidate.accepted_state.service_did.as_str().as_bytes(),
626 );
627 h.update(&candidate.accepted_state.expires_at_unix_ms.to_be_bytes());
628 h.update(&candidate.accepted_state.response_ed25519);
629 hash_framed(&mut h, &candidate.accepted_state.response_ml_dsa65);
630 h.update(&candidate.source_signer);
631 h.update(&candidate.expires_at_unix_ms.to_be_bytes());
632 if let Some(kem) = &candidate.request_kem_recipient {
633 h.update(&kem.not_after_unix_ms.to_be_bytes());
634 }
635 h.finalize().to_hex().to_string()
636}
637
638#[cfg(test)]
639fn rejection_reason(
640 query: &ServiceQuery,
641 candidate: &ServiceCandidate,
642 now_unix_ms: i64,
643) -> Option<&'static str> {
644 if canonical_service_name(&candidate.service_name)
645 .ok()
646 .as_deref()
647 != Some(query.service_name.as_str())
648 {
649 return Some("service-name-mismatch");
650 }
651 if !candidate.service_did.is_did_at9p()
652 || candidate.service_did != candidate.accepted_state.service_did
653 {
654 return Some("missing-or-mismatched-accepted-identity");
655 }
656 if candidate.source_signer != candidate.accepted_state.response_ed25519 {
657 return Some("announcement-signer-not-current");
658 }
659 if candidate.response_verifying_key != candidate.accepted_state.response_ed25519
660 || candidate.response_ml_dsa65 != candidate.accepted_state.response_ml_dsa65
661 {
662 return Some("response-key-not-current");
663 }
664 if !candidate
665 .response_key_id
666 .starts_with(&format!("{}#", candidate.service_did))
667 || crate::crypto::pq::ml_dsa_vk_from_bytes(&candidate.response_ml_dsa65).is_err()
668 {
669 return Some("missing-or-invalid-response-key-material");
670 }
671 if !query
672 .required_capabilities
673 .is_subset(&candidate.capabilities)
674 {
675 return Some("missing-capability");
676 }
677 if candidate.expires_at_unix_ms <= now_unix_ms
678 || candidate.accepted_state.expires_at_unix_ms <= now_unix_ms
679 {
680 return Some("expired-candidate-or-state");
681 }
682 match query.profile {
683 ResolverProfile::NetworkDiscovery if !network_reach(&candidate.transport) => {
684 return Some("local-reach-for-network-profile");
685 }
686 ResolverProfile::NativeIrohRequired if !native_iroh_reach(&candidate.transport) => {
687 return Some("non-iroh-reach-for-native-profile");
688 }
689 ResolverProfile::BrowserWebTransport
690 if !browser_webtransport_reach(&candidate.transport) =>
691 {
692 return Some("non-quic-reach-for-browser-profile");
693 }
694 ResolverProfile::LocalInproc
695 if !matches!(candidate.transport.endpoint, EndpointType::Inproc { .. }) =>
696 {
697 return Some("non-inproc-reach-for-local-profile");
698 }
699 ResolverProfile::Ipc
700 if !matches!(
701 candidate.transport.endpoint,
702 EndpointType::Ipc { .. } | EndpointType::SystemdFd { .. }
703 ) =>
704 {
705 return Some("non-ipc-reach-for-ipc-profile");
706 }
707 _ => {}
708 }
709 let Some(kem) = &candidate.request_kem_recipient else {
710 return Some("missing-request-kem-recipient");
711 };
712 if !kem
713 .key_id
714 .starts_with(&format!("{}#", candidate.service_did))
715 || kem.not_after_unix_ms <= now_unix_ms
716 || kem.recipient.suite_id != crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768
717 || kem.recipient.eks.len() != kem.recipient.suite_id.components().len()
718 || crate::crypto::hybrid_kem::RecipientPublic::decode(&kem.recipient.encode()).is_err()
719 {
720 return Some("invalid-expired-or-nonhybrid-kem-recipient");
721 }
722 None
723}
724
725#[cfg(test)]
728pub async fn retry_validated_candidates<T, F, Fut>(
729 mut ordered: Vec<SelectedService>,
730 max_attempts: usize,
731 mut attempt: F,
732) -> anyhow::Result<T>
733where
734 F: FnMut(&SelectedService) -> Fut,
735 Fut: std::future::Future<Output = anyhow::Result<T>>,
736{
737 anyhow::ensure!(max_attempts > 0, "retry bound must be non-zero");
738 let authority = ordered
739 .first()
740 .ok_or_else(|| anyhow!("validated retry set is empty"))?;
741 anyhow::ensure!(
742 ordered.iter().all(|resolved| {
743 resolved.service_name == authority.service_name
744 && resolved.service_did == authority.service_did
745 && resolved.response_verifying_key == authority.response_verifying_key
746 && resolved.response_ml_dsa65 == authority.response_ml_dsa65
747 && resolved.response_key_id == authority.response_key_id
748 && resolved.request_kem_recipient == authority.request_kem_recipient
749 && resolved.evidence.accepted_state_digest
750 == authority.evidence.accepted_state_digest
751 && resolved.evidence.accepted_state_epoch == authority.evidence.accepted_state_epoch
752 }),
753 "validated retry set crosses service authority"
754 );
755 ordered.sort_by(|a, b| {
756 b.expires_at_unix_ms
757 .cmp(&a.expires_at_unix_ms)
758 .then_with(|| {
759 transport_fingerprint(&a.transport).cmp(&transport_fingerprint(&b.transport))
760 })
761 .then_with(|| {
762 a.evidence
763 .selected_fingerprint
764 .cmp(&b.evidence.selected_fingerprint)
765 })
766 });
767 ordered.dedup_by(|a, b| a.evidence.selected_fingerprint == b.evidence.selected_fingerprint);
768 let mut last_error = None;
769 for resolved in ordered.iter().take(max_attempts.min(16)) {
770 match attempt(resolved).await {
771 Ok(value) => return Ok(value),
772 Err(error) => last_error = Some(error),
773 }
774 }
775 Err(last_error.unwrap_or_else(|| anyhow!("validated retry set exhausted")))
776}
777
778#[cfg(test)]
780pub fn select_service_candidate(
781 query: &ServiceQuery,
782 candidates: Vec<ServiceCandidate>,
783 now_unix_ms: i64,
784) -> anyhow::Result<SelectedService> {
785 let mut decisions = Vec::with_capacity(candidates.len());
786 let mut valid = Vec::new();
787 for candidate in candidates {
788 let fingerprint = candidate_fingerprint(&candidate);
789 if let Some(reason) = rejection_reason(query, &candidate, now_unix_ms) {
790 decisions.push(CandidateDecision {
791 candidate_fingerprint: fingerprint,
792 accepted: false,
793 reason: reason.to_owned(),
794 });
795 } else {
796 decisions.push(CandidateDecision {
797 candidate_fingerprint: fingerprint.clone(),
798 accepted: true,
799 reason: "validated".to_owned(),
800 });
801 valid.push((fingerprint, candidate));
802 }
803 }
804 anyhow::ensure!(!valid.is_empty(), "no validated service candidates");
805
806 let authority = &valid[0].1;
807 anyhow::ensure!(
808 valid.iter().all(|(_, candidate)| {
809 candidate.service_did == authority.service_did
810 && candidate.response_verifying_key == authority.response_verifying_key
811 && candidate.response_ml_dsa65 == authority.response_ml_dsa65
812 && candidate.response_key_id == authority.response_key_id
813 && candidate.request_kem_recipient == authority.request_kem_recipient
814 && candidate.accepted_state == authority.accepted_state
815 }),
816 "ambiguous validated service authority"
817 );
818
819 valid.sort_by(|(af, a), (bf, b)| {
820 b.accepted_state
821 .epoch
822 .cmp(&a.accepted_state.epoch)
823 .then_with(|| b.expires_at_unix_ms.cmp(&a.expires_at_unix_ms))
824 .then_with(|| a.service_did.cmp(&b.service_did))
825 .then_with(|| {
826 transport_fingerprint(&a.transport).cmp(&transport_fingerprint(&b.transport))
827 })
828 .then_with(|| af.cmp(bf))
829 });
830 valid.dedup_by(|(af, _), (bf, _)| af == bf);
831 let (selected_fingerprint, selected) = valid.remove(0);
832
833 decisions.sort_by(|a, b| a.candidate_fingerprint.cmp(&b.candidate_fingerprint));
834 let response_verifying_key = VerifyingKey::from_bytes(&selected.response_verifying_key)
835 .map_err(|e| anyhow!("invalid selected response verifying key: {e}"))?;
836 let request_kem_recipient = selected
837 .request_kem_recipient
838 .ok_or_else(|| anyhow!("validated candidate lost request KEM recipient"))?;
839 let expires_at_unix_ms = selected
840 .expires_at_unix_ms
841 .min(selected.accepted_state.expires_at_unix_ms)
842 .min(request_kem_recipient.not_after_unix_ms);
843 Ok(SelectedService {
844 service_name: selected.service_name,
845 service_did: selected.service_did,
846 response_verifying_key,
847 response_ml_dsa65: selected.response_ml_dsa65,
848 response_key_id: selected.response_key_id,
849 request_kem_recipient,
850 transport: selected.transport,
851 capabilities: selected.capabilities,
852 expires_at_unix_ms,
853 evidence: ResolutionEvidence {
854 accepted_state_digest: selected.accepted_state.digest,
855 accepted_state_epoch: selected.accepted_state.epoch,
856 selected_fingerprint,
857 ordered_decisions: decisions,
858 },
859 })
860}
861
862#[cfg(test)]
867pub fn select_service_candidates(
868 query: &ServiceQuery,
869 mut candidates: Vec<ServiceCandidate>,
870 now_unix_ms: i64,
871) -> anyhow::Result<Vec<SelectedService>> {
872 let mut ordered = Vec::new();
873 loop {
874 let selected = match select_service_candidate(query, candidates.clone(), now_unix_ms) {
875 Ok(selected) => selected,
876 Err(error) if !ordered.is_empty() && error.to_string().contains("no validated") => {
877 break;
878 }
879 Err(error) => return Err(error),
880 };
881 let fingerprint = selected.evidence.selected_fingerprint.clone();
882 candidates.retain(|candidate| candidate_fingerprint(candidate) != fingerprint);
883 ordered.push(selected);
884 }
885 Ok(ordered)
886}
887
888#[async_trait::async_trait]
900pub trait Resolver: Send + Sync {
901 async fn resolve(&self, name: &str, kind: SocketKind) -> anyhow::Result<TransportConfig>;
907}
908
909#[derive(Debug, Clone, Copy, PartialEq, Eq)]
916pub enum ResolverProfile {
917 LocalInproc,
919 Ipc,
921 NetworkDiscovery,
923 NativeIrohRequired,
925 BrowserWebTransport,
927}
928
929pub struct NetworkDiscoveryResolver {
935 inner: Arc<dyn Resolver>,
936}
937
938impl NetworkDiscoveryResolver {
939 pub fn new(inner: Arc<dyn Resolver>) -> Self {
940 Self { inner }
941 }
942}
943
944#[async_trait::async_trait]
945impl Resolver for NetworkDiscoveryResolver {
946 async fn resolve(&self, name: &str, kind: SocketKind) -> anyhow::Result<TransportConfig> {
947 let transport = self.inner.resolve(name, kind).await?;
948 match &transport.endpoint {
949 EndpointType::Inproc { .. }
950 | EndpointType::Ipc { .. }
951 | EndpointType::SystemdFd { .. } => Err(anyhow!(
952 "network-discovery resolver returned same-host endpoint for service '{name}' ({kind:?})"
953 )),
954 EndpointType::Iroh { .. } => Ok(transport),
955 EndpointType::Quic { .. } => Err(anyhow!(
956 "native Iroh resolver returned QUIC/WebTransport reach for service '{name}' ({kind:?})"
957 )),
958 }
959 }
960}
961
962static GLOBAL_RESOLVER: RwLock<Option<Arc<dyn Resolver>>> = RwLock::new(None);
967#[cfg(test)]
968static GLOBAL_SERVICE_RESOLVER: RwLock<Option<Arc<dyn ServiceResolver>>> = RwLock::new(None);
969
970#[cfg(test)]
974pub fn set_global_service(resolver: Arc<dyn ServiceResolver>) {
975 *GLOBAL_SERVICE_RESOLVER.write() = Some(resolver);
976}
977
978#[cfg(test)]
980pub fn try_global_service() -> Option<Arc<dyn ServiceResolver>> {
981 GLOBAL_SERVICE_RESOLVER.read().clone()
982}
983
984pub fn set_global(resolver: Arc<dyn Resolver>) {
1001 *GLOBAL_RESOLVER.write() = Some(resolver);
1002}
1003
1004pub fn try_global() -> Option<Arc<dyn Resolver>> {
1008 GLOBAL_RESOLVER.read().clone()
1009}
1010
1011#[deprecated(note = "use try_global() instead for graceful degradation (D9)")]
1017pub fn global() -> Arc<dyn Resolver> {
1018 #[allow(clippy::expect_used)] GLOBAL_RESOLVER
1020 .read()
1021 .clone()
1022 .expect("Global resolver not initialized — call resolver::set_global() first")
1023}
1024
1025#[cfg(test)]
1026#[allow(clippy::expect_used, clippy::unwrap_used)]
1027mod tests {
1028 use super::*;
1029 use std::sync::atomic::{AtomicUsize, Ordering};
1030
1031 fn candidate(tag: u8, transport: TransportConfig) -> ServiceCandidate {
1032 let ed = crate::crypto::SigningKey::from_bytes(&[tag; 32])
1033 .verifying_key()
1034 .to_bytes();
1035 let (_pq_sk, pq_vk) = crate::crypto::pq::ml_dsa_generate_keypair();
1036 let pq = crate::crypto::pq::ml_dsa_vk_bytes(&pq_vk);
1037 let kem = crate::crypto::hybrid_kem::generate_recipient(
1038 crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768,
1039 )
1040 .unwrap_or_else(|e| panic!("test KEM generation failed: {e}"))
1041 .public();
1042 let did = Did::from(format!("did:at9p:service-{tag}"));
1043 ServiceCandidate {
1044 service_name: "model".to_owned(),
1045 service_did: did.clone(),
1046 response_verifying_key: ed,
1047 response_ml_dsa65: pq.clone(),
1048 response_key_id: format!("{did}#response-{tag}"),
1049 request_kem_recipient: Some(AnchoredKemRecipient {
1050 key_id: format!("{did}#kem-{tag}"),
1051 recipient: kem,
1052 not_after_unix_ms: 20_000,
1053 }),
1054 transport,
1055 capabilities: ["hyprstream-rpc/1".to_owned()].into_iter().collect(),
1056 accepted_state: AcceptedStateEvidence {
1057 service_did: did,
1058 digest: [tag; 64],
1059 epoch: u64::from(tag),
1060 expires_at_unix_ms: 20_000,
1061 response_ed25519: ed,
1062 response_ml_dsa65: pq,
1063 },
1064 source_signer: ed,
1065 expires_at_unix_ms: 20_000,
1066 }
1067 }
1068
1069 fn network_query() -> ServiceQuery {
1070 ServiceQuery::network("model").unwrap_or_else(|e| panic!("test query must be valid: {e}"))
1071 }
1072
1073 #[test]
1074 fn identity_bound_selection_positive_control() {
1075 let candidate = candidate(7, TransportConfig::iroh([9; 32], Vec::new(), None));
1076 let expected_response = candidate.response_verifying_key;
1077 let selected = select_service_candidate(&network_query(), vec![candidate], 1_000)
1078 .unwrap_or_else(|e| panic!("valid candidate rejected: {e}"));
1079 assert_eq!(selected.service_did.as_str(), "did:at9p:service-7");
1080 assert_eq!(
1081 selected.response_verifying_key.to_bytes(),
1082 expected_response
1083 );
1084 assert!(selected.request_kem_recipient.key_id.ends_with("#kem-7"));
1085 assert_eq!(selected.evidence.accepted_state_epoch, 7);
1086 selected
1087 .crypto_stores()
1088 .unwrap_or_else(|e| panic!("selected exact crypto stores invalid: {e}"));
1089 }
1090
1091 struct AlwaysAdvancedResolver {
1092 snapshot: SelectedService,
1093 resolves: AtomicUsize,
1094 checks: AtomicUsize,
1095 }
1096
1097 #[async_trait::async_trait]
1098 impl ServiceResolver for AlwaysAdvancedResolver {
1099 async fn resolve_service(&self, _query: ServiceQuery) -> anyhow::Result<SelectedService> {
1100 self.resolves.fetch_add(1, Ordering::SeqCst);
1101 Ok(self.snapshot.clone())
1102 }
1103
1104 async fn ensure_current(&self, _resolved: &SelectedService) -> anyhow::Result<()> {
1105 self.checks.fetch_add(1, Ordering::SeqCst);
1106 anyhow::bail!("accepted state advanced")
1107 }
1108 }
1109
1110 #[tokio::test]
1111 async fn lazy_first_send_re_resolves_once_and_refuses_before_transport() {
1112 let snapshot = select_service_candidate(
1113 &network_query(),
1114 vec![candidate(
1115 8,
1116 TransportConfig::iroh([8; 32], Vec::new(), None),
1117 )],
1118 1_000,
1119 )
1120 .expect("fixture snapshot");
1121 let resolver = Arc::new(AlwaysAdvancedResolver {
1122 snapshot,
1123 resolves: AtomicUsize::new(0),
1124 checks: AtomicUsize::new(0),
1125 });
1126 let signing = crate::crypto::SigningKey::from_bytes(&[0x41; 32]);
1127 let client = ResolvedRpcClient::new("model", signing, None, resolver.clone())
1128 .expect("resolved lazy client");
1129 let error = client
1130 .call(vec![1, 2, 3])
1131 .await
1132 .expect_err("advanced state dialed");
1133 assert!(
1134 error.to_string().contains("remained invalid"),
1135 "unexpected refusal: {error:#}"
1136 );
1137 assert_eq!(resolver.resolves.load(Ordering::SeqCst), 2);
1138 assert_eq!(resolver.checks.load(Ordering::SeqCst), 2);
1139 }
1140
1141 #[test]
1142 fn only_explicit_pre_dispatch_errors_are_retry_safe() {
1143 let ordinary = anyhow!("service rejected request after dispatch");
1144 assert!(!crate::transport_traits::is_pre_dispatch_transport_error(
1145 &ordinary
1146 ));
1147 let marked = anyhow::Error::new(crate::transport_traits::PreDispatchTransportError::new(
1148 anyhow!("dial refused"),
1149 ));
1150 assert!(crate::transport_traits::is_pre_dispatch_transport_error(
1151 &marked
1152 ));
1153 }
1154
1155 #[test]
1156 fn required_properties_fail_before_dial() {
1157 let query = network_query();
1158 assert!(select_service_candidate(&query, Vec::new(), 1_000).is_err());
1159
1160 let base = candidate(3, TransportConfig::iroh([3; 32], Vec::new(), None));
1161 let mut cases = Vec::new();
1162 let mut expired = base.clone();
1163 expired.expires_at_unix_ms = 999;
1164 cases.push(expired);
1165 let mut expired_state = base.clone();
1166 expired_state.accepted_state.expires_at_unix_ms = 999;
1167 cases.push(expired_state);
1168 let mut missing_capability = base.clone();
1169 missing_capability.capabilities.clear();
1170 cases.push(missing_capability);
1171 let mut wrong_response = base.clone();
1172 wrong_response.response_verifying_key = [8; 32];
1173 cases.push(wrong_response);
1174 let mut wrong_source = base.clone();
1175 wrong_source.source_signer = [8; 32];
1176 cases.push(wrong_source);
1177 let mut omitted_pq = base.clone();
1178 omitted_pq.response_ml_dsa65.clear();
1179 omitted_pq.accepted_state.response_ml_dsa65.clear();
1180 cases.push(omitted_pq);
1181 let mut missing_kem = base.clone();
1182 missing_kem.request_kem_recipient = None;
1183 cases.push(missing_kem);
1184 let mut expired_kem = base.clone();
1185 expired_kem
1186 .request_kem_recipient
1187 .as_mut()
1188 .expect("fixture KEM")
1189 .not_after_unix_ms = 999;
1190 cases.push(expired_kem);
1191 let mut omitted_kem_component = base.clone();
1192 omitted_kem_component
1193 .request_kem_recipient
1194 .as_mut()
1195 .expect("fixture KEM")
1196 .recipient
1197 .eks
1198 .pop();
1199 cases.push(omitted_kem_component);
1200 let mut cross_service_kem = base.clone();
1201 cross_service_kem
1202 .request_kem_recipient
1203 .as_mut()
1204 .expect("fixture KEM")
1205 .key_id = "did:at9p:other#kem".to_owned();
1206 cases.push(cross_service_kem);
1207 let mut wrong_identity = base.clone();
1208 wrong_identity.service_did = Did::from("did:at9p:other");
1209 cases.push(wrong_identity);
1210 let mut reach_only = base.clone();
1211 reach_only.service_did = Did::default();
1212 reach_only.accepted_state.service_did = Did::default();
1213 cases.push(reach_only);
1214 let mut local = base;
1215 local.transport = TransportConfig::inproc("hyprstream/model");
1216 cases.push(local);
1217
1218 for invalid in cases {
1219 assert!(
1220 select_service_candidate(&query, vec![invalid], 1_000).is_err(),
1221 "invalid candidate reached dial selection"
1222 );
1223 }
1224 }
1225
1226 #[test]
1227 fn candidate_permutations_select_identically() {
1228 let mut a = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1229 a.capabilities.extend(["x".to_owned(), "y".to_owned()]);
1230 let mut b = a.clone();
1231 b.capabilities.remove("x");
1232 b.capabilities.remove("y");
1233 b.capabilities.insert("x\0y".to_owned());
1234 assert_ne!(candidate_fingerprint(&a), candidate_fingerprint(&b));
1235 b.transport = TransportConfig::iroh([2; 32], Vec::new(), None);
1236 let first = select_service_candidate(&network_query(), vec![a.clone(), b.clone()], 1_000)
1237 .unwrap_or_else(|e| panic!("selection failed: {e}"));
1238 let second = select_service_candidate(&network_query(), vec![b, a], 1_000)
1239 .unwrap_or_else(|e| panic!("selection failed: {e}"));
1240 assert_eq!(first.service_did, second.service_did);
1241 assert_eq!(first.transport, second.transport);
1242 assert_eq!(first.response_verifying_key, second.response_verifying_key);
1243 assert_eq!(first.request_kem_recipient, second.request_kem_recipient);
1244 assert_eq!(first.evidence, second.evidence);
1245 }
1246
1247 #[test]
1248 fn distinct_valid_identities_are_ambiguous() {
1249 let a = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1250 let b = candidate(2, TransportConfig::iroh([2; 32], Vec::new(), None));
1251 let error = select_service_candidate(&network_query(), vec![a, b], 1_000)
1252 .expect_err("distinct service authorities were ranked as interchangeable");
1253 assert!(error.to_string().contains("ambiguous"));
1254 }
1255
1256 #[test]
1257 fn explicit_local_profiles_accept_only_their_local_reach() {
1258 let inproc_query = ServiceQuery::new(
1259 "model",
1260 ["hyprstream-rpc/1".to_owned()],
1261 ResolverProfile::LocalInproc,
1262 1,
1263 )
1264 .expect("local query");
1265 assert!(select_service_candidate(
1266 &inproc_query,
1267 vec![candidate(4, TransportConfig::inproc("hyprstream/model"))],
1268 1_000,
1269 )
1270 .is_ok());
1271 assert!(select_service_candidate(
1272 &inproc_query,
1273 vec![candidate(4, TransportConfig::ipc("/tmp/model.sock"))],
1274 1_000,
1275 )
1276 .is_err());
1277
1278 let ipc_query = ServiceQuery::new(
1279 "model",
1280 ["hyprstream-rpc/1".to_owned()],
1281 ResolverProfile::Ipc,
1282 1,
1283 )
1284 .expect("IPC query");
1285 assert!(select_service_candidate(
1286 &ipc_query,
1287 vec![candidate(5, TransportConfig::ipc("/tmp/model.sock"))],
1288 1_000,
1289 )
1290 .is_ok());
1291 }
1292
1293 #[tokio::test]
1294 async fn retries_are_bounded_to_validated_order() {
1295 let first_candidate = candidate(1, TransportConfig::iroh([1; 32], Vec::new(), None));
1296 let mut second_candidate = first_candidate.clone();
1297 second_candidate.transport = TransportConfig::iroh([2; 32], Vec::new(), None);
1298 let first = select_service_candidate(&network_query(), vec![first_candidate], 1_000)
1299 .unwrap_or_else(|e| panic!("selection failed: {e}"));
1300 let second = select_service_candidate(&network_query(), vec![second_candidate], 1_000)
1301 .unwrap_or_else(|e| panic!("selection failed: {e}"));
1302 let seen = Arc::new(parking_lot::Mutex::new(Vec::new()));
1303 let observed = Arc::clone(&seen);
1304 let result: anyhow::Result<()> =
1305 retry_validated_candidates(vec![first, second.clone()], 1, move |resolved| {
1306 observed.lock().push(resolved.service_did.clone());
1307 std::future::ready(Err(anyhow!("sentinel dial failure")))
1308 })
1309 .await;
1310 assert!(result.is_err());
1311 assert_eq!(seen.lock().len(), 1);
1312
1313 let other = select_service_candidate(
1314 &network_query(),
1315 vec![candidate(
1316 2,
1317 TransportConfig::iroh([3; 32], Vec::new(), None),
1318 )],
1319 1_000,
1320 )
1321 .unwrap_or_else(|e| panic!("selection failed: {e}"));
1322 let crossed: anyhow::Result<()> =
1323 retry_validated_candidates(vec![second, other], 2, |_| std::future::ready(Ok(())))
1324 .await;
1325 assert!(crossed.is_err());
1326 }
1327
1328 struct StaticResolver(TransportConfig);
1329
1330 #[async_trait::async_trait]
1331 impl Resolver for StaticResolver {
1332 async fn resolve(&self, _name: &str, _kind: SocketKind) -> anyhow::Result<TransportConfig> {
1333 Ok(self.0.clone())
1334 }
1335 }
1336
1337 #[tokio::test]
1338 async fn network_discovery_resolver_rejects_inproc_reach() {
1339 let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(
1340 TransportConfig::inproc("hyprstream/policy"),
1341 )));
1342
1343 let err = match resolver.resolve("policy", SocketKind::Rep).await {
1344 Ok(endpoint) => panic!("network resolver accepted local endpoint: {endpoint:?}"),
1345 Err(err) => err,
1346 };
1347 assert!(
1348 err.to_string().contains("same-host endpoint"),
1349 "unexpected error: {err}"
1350 );
1351 }
1352
1353 #[tokio::test]
1354 async fn network_discovery_resolver_rejects_same_host_reach() {
1355 for local in [
1356 TransportConfig::ipc("/run/hyprstream/policy.sock"),
1357 TransportConfig::systemd_fd(3, "/run/hyprstream/policy.sock"),
1358 ] {
1359 let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(local)));
1360 let err = match resolver.resolve("policy", SocketKind::Rep).await {
1361 Ok(endpoint) => {
1362 panic!("network resolver accepted same-host endpoint: {endpoint:?}")
1363 }
1364 Err(err) => err,
1365 };
1366 assert!(
1367 err.to_string().contains("same-host endpoint"),
1368 "unexpected error: {err}"
1369 );
1370 }
1371 }
1372
1373 #[tokio::test]
1374 async fn native_iroh_resolver_rejects_quic_reach() {
1375 let addr = "127.0.0.1:9443"
1376 .parse()
1377 .unwrap_or_else(|err| panic!("test socket address must parse: {err}"));
1378 let quic = TransportConfig::quic(addr, "policy.local");
1379 let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(quic.clone())));
1380
1381 let error = resolver
1382 .resolve("policy", SocketKind::Rep)
1383 .await
1384 .expect_err("native Iroh resolver must reject QUIC/WebTransport reach");
1385 assert!(error.to_string().contains("QUIC/WebTransport"));
1386 }
1387
1388 #[tokio::test]
1389 async fn network_discovery_resolver_accepts_iroh_reach() {
1390 let iroh = TransportConfig::iroh([7; 32], Vec::new(), None);
1391 let resolver = NetworkDiscoveryResolver::new(Arc::new(StaticResolver(iroh.clone())));
1392
1393 let endpoint = resolver
1394 .resolve("policy", SocketKind::Rep)
1395 .await
1396 .unwrap_or_else(|err| panic!("network resolver rejected iroh endpoint: {err}"));
1397 assert_eq!(endpoint, iroh);
1398 }
1399}