Skip to main content

hyprstream_rpc/
rpc_client.rs

1//! Unified RPC client parameterized over Signer and Transport.
2//!
3//! `RpcClientImpl<S, T>` handles envelope construction, signing, response verification,
4//! and streaming setup. Same code compiles to native and wasm32 — only the type
5//! parameters differ:
6//!
7//! - Native: `RpcClient<LocalSigner, ZmqConnection>`
8//! - WASM:   `RpcClient<JsSigner, WtConnection>`
9//!
10//! Generated service clients (e.g., `RegistryClient`) use `Arc<dyn RpcClient>`
11//! for object-safe dynamic dispatch.
12
13use std::sync::atomic::{AtomicU64, Ordering};
14use std::sync::Arc;
15
16use anyhow::Result;
17use async_trait::async_trait;
18
19use crate::capnp::{FromCapnp, ToCapnp};
20use crate::crypto::hybrid_kem::KemTrustStore;
21use crate::crypto::VerifyingKey;
22use crate::envelope::{self, RequestEnvelope, SignedEnvelope};
23use crate::stream_consumer::{StreamHandle, StreamHandleImpl};
24use crate::transport_traits::{Signer, Transport};
25
26type TokenProviderBox = Arc<dyn Fn() -> Option<String> + Send + Sync>;
27
28/// Revalidates external resolution authority immediately before envelope
29/// construction and sealing.
30#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
31#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
32pub trait PreSealGuard: Send + Sync {
33    async fn ensure_current(&self) -> Result<()>;
34
35    /// A browser guard may supply a fresh projection of its unchanged anchor.
36    /// The result belongs to this request only; legacy guards are unchanged.
37    async fn current_browser_binding(
38        &self,
39    ) -> Result<Option<crate::browser_provisioning::BrowserRequestBinding>> {
40        self.ensure_current().await?;
41        Ok(None)
42    }
43}
44
45/// Builds a holder proof after all forwarded recipients exist. `capnp_body`
46/// is the application body before browser carrier framing, matching what
47/// dispatch recovers and verifies. This is opt-in per client.
48#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
49#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
50pub trait FederateProofProvider: Send + Sync {
51    async fn proof_for(&self, envelope: &RequestEnvelope, capnp_body: &[u8]) -> Result<Vec<u8>>;
52}
53
54/// Non-cloneable, non-serializable one-call response decapsulation material.
55/// The component secret bytes are `Zeroizing` inside `RecipientKeypair` and
56/// are dropped immediately after the sole response-open attempt.
57struct ResponseRecipientSecret {
58    keypair: crate::crypto::hybrid_kem::RecipientKeypair,
59    #[cfg(test)]
60    drop_probe: Option<Arc<std::sync::atomic::AtomicUsize>>,
61}
62
63#[cfg(test)]
64impl Drop for ResponseRecipientSecret {
65    fn drop(&mut self) {
66        if let Some(probe) = &self.drop_probe {
67            probe.fetch_add(1, Ordering::SeqCst);
68        }
69    }
70}
71
72struct PendingResponse {
73    request_id: u64,
74    request_iat: i64,
75    request_nonce: [u8; 16],
76    server_identity: [u8; 32],
77    recipient_public: crate::crypto::hybrid_kem::RecipientPublic,
78    service_domain: String,
79    secret: ResponseRecipientSecret,
80}
81
82impl std::fmt::Debug for PendingResponse {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        f.debug_struct("PendingResponse")
85            .field("request_id", &self.request_id)
86            .field("server_identity", &hex::encode(self.server_identity))
87            .field("service_domain", &self.service_domain)
88            .finish_non_exhaustive()
89    }
90}
91
92impl PendingResponse {
93    fn open(self, envelope: &crate::envelope::ResponseEnvelope) -> Result<Vec<u8>> {
94        if envelope.request_id != self.request_id {
95            anyhow::bail!(
96                "response request id {} does not match pending request {}",
97                envelope.request_id,
98                self.request_id
99            );
100        }
101        envelope.open_encrypted(
102            &self.secret.keypair,
103            &self.recipient_public,
104            self.request_iat,
105            &self.request_nonce,
106            &self.server_identity,
107            &self.service_domain,
108        )
109    }
110}
111
112// ============================================================================
113// Per-call options (non-mutating, Send+Sync, owned data)
114// ============================================================================
115
116/// Per-call options for RPC requests.
117///
118/// Used with `call_with_options()` and `RequestBuilder` to pass per-call
119/// authentication context without mutating shared client state.
120/// Safe for concurrent use — each call gets its own owned `CallOptions`.
121///
122/// # Security
123///
124/// - `jwt`: Overrides the client's default JWT for this call.
125///   Used when a service needs to present a specific token.
126/// - `delegated_bearer`: Bearer token relayed on behalf of a user.
127///   Only explicitly pinned service identities may set this. The server
128///   resolves the subject from the verified bearer, not the relay identity.
129#[derive(Debug, Clone, Default)]
130pub struct CallOptions {
131    /// Override the client's default JWT for this call.
132    pub jwt: Option<String>,
133    /// Bearer token relayed on behalf of a user (delegation).
134    pub delegated_bearer: Option<String>,
135}
136
137impl CallOptions {
138    /// Create empty options (no overrides).
139    pub fn new() -> Self {
140        Self::default()
141    }
142
143    /// Set a per-call JWT override.
144    pub fn jwt(mut self, token: impl Into<String>) -> Self {
145        self.jwt = Some(token.into());
146        self
147    }
148
149    /// Set a delegated bearer token for relay.
150    pub fn delegated_bearer(mut self, token: impl Into<String>) -> Self {
151        self.delegated_bearer = Some(token.into());
152        self
153    }
154}
155
156// ============================================================================
157// Per-call request builder
158// ============================================================================
159
160/// Per-call request builder for custom authentication options.
161///
162/// Created by `client.request()`, captures per-call auth context
163/// without mutating the shared `Arc<dyn RpcClient>`. Safe for
164/// concurrent use with connection pooling.
165///
166/// # Example
167///
168/// ```ignore
169/// let response = model_client.request()
170///     .delegated_bearer(user_bearer_token)
171///     .call(payload)
172///     .await?;
173/// ```
174pub struct RequestBuilder<'a> {
175    client: &'a Arc<dyn RpcClient>,
176    service_domain: Option<&'static str>,
177    jwt: Option<String>,
178    delegated_bearer: Option<String>,
179}
180
181impl<'a> std::fmt::Debug for RequestBuilder<'a> {
182    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
183        f.debug_struct("RequestBuilder")
184            .field("jwt", &self.jwt.as_ref().map(|_| "***"))
185            .field(
186                "delegated_bearer",
187                &self.delegated_bearer.as_ref().map(|_| "***"),
188            )
189            .finish()
190    }
191}
192
193impl<'a> RequestBuilder<'a> {
194    /// Create a builder wrapping the given client.
195    pub fn new(client: &'a Arc<dyn RpcClient>) -> Self {
196        Self {
197            client,
198            service_domain: None,
199            jwt: None,
200            delegated_bearer: None,
201        }
202    }
203
204    /// Create a builder bound to a generated client's canonical service.
205    pub fn for_service(client: &'a Arc<dyn RpcClient>, service_domain: &'static str) -> Self {
206        Self {
207            client,
208            service_domain: Some(service_domain),
209            jwt: None,
210            delegated_bearer: None,
211        }
212    }
213
214    /// Set a per-call JWT override.
215    pub fn jwt(mut self, token: impl Into<String>) -> Self {
216        self.jwt = Some(token.into());
217        self
218    }
219
220    /// Set a delegated bearer token for relay.
221    pub fn delegated_bearer(mut self, token: impl Into<String>) -> Self {
222        self.delegated_bearer = Some(token.into());
223        self
224    }
225
226    /// Send a raw request with these options and return the raw response bytes.
227    pub async fn call(self, payload: Vec<u8>) -> Result<Vec<u8>> {
228        let options = CallOptions {
229            jwt: self.jwt,
230            delegated_bearer: self.delegated_bearer,
231        };
232        match self.service_domain {
233            Some(service_domain) => {
234                self.client
235                    .call_with_options_for_service(service_domain, payload, options)
236                    .await
237            }
238            None => self.client.call_with_options(payload, options).await,
239        }
240    }
241}
242
243/// Unified RPC client. Evolved from ZmqClient — same envelope, timeout,
244/// and resilience logic, parameterized over transport and signing.
245pub struct RpcClientImpl<S: Signer, T: Transport + 'static> {
246    pub signer: S,
247    pub transport: T,
248    pub server_verifying_key: Option<VerifyingKey>,
249    token_provider: Option<TokenProviderBox>,
250    request_id: AtomicU64,
251    /// Per-client response-verify policy override (#275/#277). `None` means "not
252    /// explicitly set" — in that case `unwrap_response` consults the process-
253    /// global response verify config ([`crate::envelope::global_response_verify_policy`]),
254    /// which is fail-closed `Hybrid` when the daemon installed it (or when
255    /// uninstalled in production). `Some(_)` pins the policy for this client,
256    /// bypassing the global default (advanced / tests).
257    response_verify_policy: Option<crate::crypto::CryptoPolicy>,
258    /// Per-client kid-anchored ML-DSA-65 trust store used to resolve the server's
259    /// PQ key for `ResponseEnvelope` verification (required under `Hybrid`). `None`
260    /// falls back to the process-global response store
261    /// ([`crate::envelope::global_response_pq_store`]).
262    response_pq_store: Option<std::sync::Arc<dyn crate::envelope::PqTrustStore>>,
263    /// Per-client kid-anchored `#mesh-kem` trust store used to encrypt request
264    /// envelopes for carriers that forbid cleartext. Bindings are established
265    /// out-of-band by DID keyAgreement / peer attestation; absence fails closed.
266    request_kem_store: Option<Arc<dyn KemTrustStore>>,
267    pre_seal_guard: Option<Arc<dyn PreSealGuard>>,
268    browser_provisioning_binding: Option<crate::browser_provisioning::BrowserRequestBinding>,
269    federate_proof_provider: Option<Arc<dyn FederateProofProvider>>,
270    #[cfg(test)]
271    response_secret_drop_probe: Option<Arc<std::sync::atomic::AtomicUsize>>,
272}
273
274impl<S: Signer, T: Transport + 'static> RpcClientImpl<S, T> {
275    /// Create a new RPC client.
276    ///
277    /// `server_verifying_key`: `None` skips response signature verification
278    /// (TLS cert pinning still protects the connection).
279    pub fn new(signer: S, transport: T, server_verifying_key: Option<VerifyingKey>) -> Self {
280        Self {
281            signer,
282            transport,
283            server_verifying_key,
284            token_provider: None,
285            request_id: AtomicU64::new(1),
286            response_verify_policy: None,
287            response_pq_store: None,
288            request_kem_store: None,
289            pre_seal_guard: None,
290            browser_provisioning_binding: None,
291            federate_proof_provider: None,
292            #[cfg(test)]
293            response_secret_drop_probe: None,
294        }
295    }
296
297    /// Enforce Hybrid (EdDSA + ML-DSA-65) verification of responses (#275),
298    /// anchoring the server's ML-DSA-65 key via `pq_store`. Under this policy a
299    /// classical-only, stripped-outer, self-cert, or unanchored response is
300    /// REJECTED (fail-closed, no silent downgrade). Mirrors the request-side
301    /// Hybrid verify config.
302    pub fn with_response_pq_store(
303        mut self,
304        pq_store: std::sync::Arc<dyn crate::envelope::PqTrustStore>,
305    ) -> Self {
306        self.response_pq_store = Some(pq_store);
307        self.response_verify_policy = Some(crate::crypto::CryptoPolicy::Hybrid);
308        self
309    }
310
311    /// Set the anchored `#mesh-kem` recipient key store used to encrypt request
312    /// envelopes when the selected transport forbids cleartext.
313    pub fn with_request_kem_store(mut self, kem_store: Arc<dyn KemTrustStore>) -> Self {
314        self.request_kem_store = Some(kem_store);
315        self
316    }
317
318    pub fn with_pre_seal_guard(mut self, guard: Arc<dyn PreSealGuard>) -> Self {
319        self.pre_seal_guard = Some(guard);
320        self
321    }
322
323    pub fn with_browser_provisioning_binding(
324        mut self,
325        binding: crate::browser_provisioning::BrowserRequestBinding,
326    ) -> Result<Self> {
327        binding.validate_shape()?;
328        self.browser_provisioning_binding = Some(binding);
329        Ok(self)
330    }
331
332    /// Enable the dedicated Federate proof sender on this client. The provider
333    /// is called separately for each request, after payload binding and
334    /// recipient generation, immediately before the envelope is sealed.
335    pub fn with_federate_proof_provider(
336        mut self,
337        provider: Arc<dyn FederateProofProvider>,
338    ) -> Self {
339        self.federate_proof_provider = Some(provider);
340        self
341    }
342
343    #[cfg(test)]
344    fn with_response_secret_drop_probe(
345        mut self,
346        probe: Arc<std::sync::atomic::AtomicUsize>,
347    ) -> Self {
348        self.response_secret_drop_probe = Some(probe);
349        self
350    }
351
352    /// Set the response-verify policy explicitly (advanced). Under `Hybrid` a
353    /// PQ trust store MUST also be set via [`Self::with_response_pq_store`].
354    /// Setting this pins the policy for this client and bypasses the process-
355    /// global response default consulted by [`Self::unwrap_response`].
356    pub fn with_response_verify_policy(mut self, policy: crate::crypto::CryptoPolicy) -> Self {
357        self.response_verify_policy = Some(policy);
358        self
359    }
360
361    /// Set a dynamic token provider called on every RPC request.
362    ///
363    /// The closure is called once per `call()` / `call_with_options()` invocation
364    /// so short-lived tokens (OAuth at+jwt, WIT) are always fresh without
365    /// reconstructing the client. On WASM, wrap `js_sys::Function` in a
366    /// `Send + Sync` newtype before passing it here (WASM is single-threaded).
367    pub fn with_token_provider<F>(mut self, f: F) -> Self
368    where
369        F: Fn() -> Option<String> + Send + Sync + 'static,
370    {
371        self.token_provider = Some(Arc::new(f));
372        self
373    }
374
375    /// Set a static default JWT. Sugar over `with_token_provider`.
376    pub fn with_default_jwt(self, token: String) -> Self {
377        self.with_token_provider(move || Some(token.clone()))
378    }
379
380    fn effective_jwt(&self) -> Option<String> {
381        self.token_provider.as_ref().and_then(|f| f())
382    }
383
384    /// Send a request and return the verified, unwrapped response payload.
385    /// Uses the client's default JWT.
386    pub async fn call(&self, payload: Vec<u8>) -> Result<Vec<u8>> {
387        self.call_bound(payload, None, None).await
388    }
389
390    /// Send a request bound to a canonical destination service. Generated
391    /// clients always use this path with their `SERVICE_NAME`.
392    pub async fn call_for_service(
393        &self,
394        service_domain: &str,
395        payload: Vec<u8>,
396    ) -> Result<Vec<u8>> {
397        self.call_bound(payload, Some(service_domain), None).await
398    }
399
400    /// Send a generated request with an explicit schema method commitment.
401    pub async fn call_for_service_with_method(
402        &self,
403        service_domain: &str,
404        method_discriminator: u16,
405        payload: Vec<u8>,
406    ) -> Result<Vec<u8>> {
407        self.call_bound(payload, Some(service_domain), Some(method_discriminator))
408            .await
409    }
410
411    async fn call_bound(
412        &self,
413        payload: Vec<u8>,
414        service_domain: Option<&str>,
415        method_discriminator: Option<u16>,
416    ) -> Result<Vec<u8>> {
417        let request_id = self.next_id();
418        let (signed_bytes, pending) = self
419            .sign_envelope(
420                request_id,
421                payload,
422                None,
423                None,
424                self.effective_jwt(),
425                None,
426                service_domain,
427                method_discriminator,
428            )
429            .await?;
430        let timeout = self.calculate_timeout();
431        let response_bytes = self.transport.send(signed_bytes, timeout).await?;
432        let (_req_id, inner) = self.unwrap_response(&response_bytes, request_id, pending)?;
433        Ok(inner)
434    }
435
436    /// Send a streaming request with ephemeral DH pubkey.
437    /// Returns the verified, unwrapped response payload (typically StreamInfo).
438    /// Uses the client's default JWT.
439    pub async fn call_streaming(
440        &self,
441        payload: Vec<u8>,
442        ephemeral_pubkey: [u8; 32],
443    ) -> Result<Vec<u8>> {
444        self.call_streaming_bound(payload, ephemeral_pubkey, None, None)
445            .await
446    }
447
448    /// Send a streaming setup request bound to a canonical destination.
449    pub async fn call_streaming_for_service(
450        &self,
451        service_domain: &str,
452        payload: Vec<u8>,
453        ephemeral_pubkey: [u8; 32],
454    ) -> Result<Vec<u8>> {
455        self.call_streaming_bound(payload, ephemeral_pubkey, Some(service_domain), None)
456            .await
457    }
458
459    /// Send a generated streaming request with an explicit schema method commitment.
460    pub async fn call_streaming_for_service_with_method(
461        &self,
462        service_domain: &str,
463        method_discriminator: u16,
464        payload: Vec<u8>,
465        ephemeral_pubkey: [u8; 32],
466    ) -> Result<Vec<u8>> {
467        self.call_streaming_bound(
468            payload,
469            ephemeral_pubkey,
470            Some(service_domain),
471            Some(method_discriminator),
472        )
473        .await
474    }
475
476    async fn call_streaming_bound(
477        &self,
478        payload: Vec<u8>,
479        ephemeral_pubkey: [u8; 32],
480        service_domain: Option<&str>,
481        method_discriminator: Option<u16>,
482    ) -> Result<Vec<u8>> {
483        let request_id = self.next_id();
484        let (signed_bytes, pending) = self
485            .sign_envelope(
486                request_id,
487                payload,
488                Some(ephemeral_pubkey),
489                None,
490                self.effective_jwt(),
491                None,
492                service_domain,
493                method_discriminator,
494            )
495            .await?;
496        let timeout = self.calculate_timeout();
497        let response_bytes = self.transport.send(signed_bytes, timeout).await?;
498        let (_req_id, inner) = self.unwrap_response(&response_bytes, request_id, pending)?;
499        Ok(inner)
500    }
501
502    /// Send an identified stream setup using the pinned classical+ML-KEM
503    /// recipient.  The caller retains the matching keypair and combines the
504    /// returned `StreamInfo.kemCiphertexts` with its accepted-current
505    /// [`IdentifiedStreamBinding`] before opening the stream.
506    pub async fn call_streaming_identified_for_service(
507        &self,
508        service_domain: &str,
509        payload: Vec<u8>,
510        recipient: crate::crypto::hybrid_kem::RecipientPublic,
511    ) -> Result<Vec<u8>> {
512        if recipient.suite_id != crate::stream_epoch::IDENTIFIED_STREAM_SUITE {
513            anyhow::bail!("identified stream recipient does not use the pinned HyKEM suite");
514        }
515        let request_id = self.next_id();
516        let (signed_bytes, pending) = self
517            .sign_envelope(
518                request_id,
519                payload,
520                None,
521                Some(recipient),
522                self.effective_jwt(),
523                None,
524                Some(service_domain),
525                None,
526            )
527            .await?;
528        let timeout = self.calculate_timeout();
529        let response_bytes = self.transport.send(signed_bytes, timeout).await?;
530        let (_req_id, inner) = self.unwrap_response(&response_bytes, request_id, pending)?;
531        Ok(inner)
532    }
533
534    /// Send a streaming request with per-call authentication options.
535    ///
536    /// Uses `options.jwt` if provided, otherwise falls back to `default_jwt`.
537    pub async fn call_streaming_with_options(
538        &self,
539        payload: Vec<u8>,
540        ephemeral_pubkey: [u8; 32],
541        options: CallOptions,
542    ) -> Result<Vec<u8>> {
543        self.call_streaming_with_options_bound(payload, ephemeral_pubkey, options, None, None)
544            .await
545    }
546
547    /// Send an option-bearing streaming request bound to a canonical destination.
548    pub async fn call_streaming_with_options_for_service(
549        &self,
550        service_domain: &str,
551        payload: Vec<u8>,
552        ephemeral_pubkey: [u8; 32],
553        options: CallOptions,
554    ) -> Result<Vec<u8>> {
555        self.call_streaming_with_options_bound(
556            payload,
557            ephemeral_pubkey,
558            options,
559            Some(service_domain),
560            None,
561        )
562        .await
563    }
564
565    /// Send an option-bearing generated streaming request bound to its service and method.
566    pub async fn call_streaming_with_options_for_service_with_method(
567        &self,
568        service_domain: &str,
569        method_discriminator: u16,
570        payload: Vec<u8>,
571        ephemeral_pubkey: [u8; 32],
572        options: CallOptions,
573    ) -> Result<Vec<u8>> {
574        self.call_streaming_with_options_bound(
575            payload,
576            ephemeral_pubkey,
577            options,
578            Some(service_domain),
579            Some(method_discriminator),
580        )
581        .await
582    }
583
584    async fn call_streaming_with_options_bound(
585        &self,
586        payload: Vec<u8>,
587        ephemeral_pubkey: [u8; 32],
588        options: CallOptions,
589        service_domain: Option<&str>,
590        method_discriminator: Option<u16>,
591    ) -> Result<Vec<u8>> {
592        let request_id = self.next_id();
593        anyhow::ensure!(
594            !(options.jwt.is_some() && options.delegated_bearer.is_some()),
595            "an RPC envelope cannot carry both a direct JWT and a delegated bearer"
596        );
597        // Delegation is an explicit principal-selection mode. Do not let a
598        // pooled client's default JWT silently take precedence over it.
599        let jwt = if options.delegated_bearer.is_some() {
600            None
601        } else {
602            options.jwt.or_else(|| self.effective_jwt())
603        };
604        let (signed_bytes, pending) = self
605            .sign_envelope(
606                request_id,
607                payload,
608                Some(ephemeral_pubkey),
609                None,
610                jwt,
611                options.delegated_bearer,
612                service_domain,
613                method_discriminator,
614            )
615            .await?;
616        let timeout = self.calculate_timeout();
617        let response_bytes = self.transport.send(signed_bytes, timeout).await?;
618        let (_req_id, inner) = self.unwrap_response(&response_bytes, request_id, pending)?;
619        Ok(inner)
620    }
621
622    /// Send a request with per-call authentication options.
623    ///
624    /// Uses `options.jwt` if provided, otherwise falls back to `default_jwt`.
625    /// Includes `options.delegated_bearer` in the envelope for relay.
626    pub async fn call_with_options(
627        &self,
628        payload: Vec<u8>,
629        options: CallOptions,
630    ) -> Result<Vec<u8>> {
631        self.call_with_options_bound(payload, options, None, None)
632            .await
633    }
634
635    /// Send an option-bearing request bound to a canonical destination.
636    pub async fn call_with_options_for_service(
637        &self,
638        service_domain: &str,
639        payload: Vec<u8>,
640        options: CallOptions,
641    ) -> Result<Vec<u8>> {
642        self.call_with_options_bound(payload, options, Some(service_domain), None)
643            .await
644    }
645
646    /// Send an option-bearing generated request bound to its service and method.
647    pub async fn call_with_options_for_service_with_method(
648        &self,
649        service_domain: &str,
650        method_discriminator: u16,
651        payload: Vec<u8>,
652        options: CallOptions,
653    ) -> Result<Vec<u8>> {
654        self.call_with_options_bound(
655            payload,
656            options,
657            Some(service_domain),
658            Some(method_discriminator),
659        )
660        .await
661    }
662
663    async fn call_with_options_bound(
664        &self,
665        payload: Vec<u8>,
666        options: CallOptions,
667        service_domain: Option<&str>,
668        method_discriminator: Option<u16>,
669    ) -> Result<Vec<u8>> {
670        let request_id = self.next_id();
671        anyhow::ensure!(
672            !(options.jwt.is_some() && options.delegated_bearer.is_some()),
673            "an RPC envelope cannot carry both a direct JWT and a delegated bearer"
674        );
675        // Delegation is an explicit principal-selection mode. Do not let a
676        // pooled client's default JWT silently take precedence over it.
677        let jwt = if options.delegated_bearer.is_some() {
678            None
679        } else {
680            options.jwt.or_else(|| self.effective_jwt())
681        };
682        let (signed_bytes, pending) = self
683            .sign_envelope(
684                request_id,
685                payload,
686                None,
687                None,
688                jwt,
689                options.delegated_bearer,
690                service_domain,
691                method_discriminator,
692            )
693            .await?;
694        let timeout = self.calculate_timeout();
695        let response_bytes = self.transport.send(signed_bytes, timeout).await?;
696        let (_req_id, inner) = self.unwrap_response(&response_bytes, request_id, pending)?;
697        Ok(inner)
698    }
699
700    /// Get the next monotonically increasing request ID.
701    pub fn next_id(&self) -> u64 {
702        self.request_id.fetch_add(1, Ordering::Relaxed)
703    }
704
705    /// Unwrap + verify a `ResponseEnvelope` (#275/#277).
706    ///
707    /// Resolves the effective response-verify policy and PQ trust store: a
708    /// per-client override (set via [`Self::with_response_pq_store`] /
709    /// [`Self::with_response_verify_policy`]) wins; otherwise the process-global
710    /// response default ([`envelope::global_response_verify_policy`] +
711    /// [`envelope::global_response_pq_store`]) is consulted. That global default
712    /// is fail-closed `Hybrid` in production — symmetric to the request-side
713    /// `global_verify_policy` — so a classical-only / stripped response is
714    /// rejected by default unless an operator opted into the `classical` escape
715    /// hatch. Under `Hybrid` the server's kid-anchored ML-DSA-65 layer is
716    /// required (no silent downgrade).
717    #[cfg(not(target_arch = "wasm32"))]
718    fn unwrap_response(
719        &self,
720        response_bytes: &[u8],
721        request_id: u64,
722        pending: Option<PendingResponse>,
723    ) -> Result<(u64, Vec<u8>)> {
724        let policy = self
725            .response_verify_policy
726            .unwrap_or_else(envelope::global_response_verify_policy);
727        // Prefer the per-client store; else the process-global one. Hold the Arc
728        // so the borrow passed to `unwrap_response_with` outlives the call.
729        let global_store = if self.response_pq_store.is_none() {
730            envelope::global_response_pq_store()
731        } else {
732            None
733        };
734        let store: Option<&dyn envelope::PqTrustStore> = self
735            .response_pq_store
736            .as_deref()
737            .or(global_store.as_deref());
738        self.unwrap_response_with_pending(response_bytes, request_id, pending, store, policy)
739    }
740
741    /// WASM response unwrap (#277 scope boundary): no process-global response
742    /// config exists on wasm, so this keeps the per-client behavior. The wasm
743    /// verify policy is owned by #158 (`wasm_api.rs`) and is intentionally NOT
744    /// changed here.
745    #[cfg(target_arch = "wasm32")]
746    fn unwrap_response(
747        &self,
748        response_bytes: &[u8],
749        request_id: u64,
750        pending: Option<PendingResponse>,
751    ) -> Result<(u64, Vec<u8>)> {
752        self.unwrap_response_with_pending(
753            response_bytes,
754            request_id,
755            pending,
756            self.response_pq_store.as_deref(),
757            self.response_verify_policy
758                .unwrap_or(crate::crypto::CryptoPolicy::Hybrid),
759        )
760    }
761
762    fn unwrap_response_with_pending(
763        &self,
764        response_bytes: &[u8],
765        request_id: u64,
766        pending: Option<PendingResponse>,
767        pq_store: Option<&dyn envelope::PqTrustStore>,
768        policy: crate::crypto::CryptoPolicy,
769    ) -> Result<(u64, Vec<u8>)> {
770        if self.transport.forbids_cleartext_envelope() {
771            let pending = pending.ok_or_else(|| {
772                anyhow::anyhow!("network response has no one-shot pending recipient")
773            })?;
774            // Carrier gate first: inspect only the bounded encrypted field and
775            // reject cleartext before copying or using the outer payload.
776            let response = envelope::read_response_envelope(response_bytes, true)?;
777            let server = self
778                .server_verifying_key
779                .as_ref()
780                .ok_or_else(|| anyhow::anyhow!("network response has no pinned server identity"))?;
781            let store = pq_store.ok_or_else(|| {
782                anyhow::anyhow!("network response has no anchored ML-DSA-65 trust store")
783            })?;
784            if store.ml_dsa_key_for(&server.to_bytes()).is_none() {
785                anyhow::bail!("network response server has no anchored ML-DSA-65 key");
786            }
787            response.verify_encrypted_with_service_domain(
788                server,
789                store,
790                &pending.service_domain,
791            )?;
792            let payload = pending.open(&response)?;
793            Ok((response.request_id, payload))
794        } else {
795            let (response_id, payload) = envelope::unwrap_response_with(
796                response_bytes,
797                self.server_verifying_key.as_ref(),
798                pq_store,
799                policy,
800            )?;
801            if response_id != request_id {
802                anyhow::bail!(
803                    "response request id {} does not match pending request {}",
804                    response_id,
805                    request_id
806                );
807            }
808            Ok((response_id, payload))
809        }
810    }
811
812    /// Build, sign, and serialize a request envelope.
813    async fn sign_envelope(
814        &self,
815        request_id: u64,
816        payload: Vec<u8>,
817        ephemeral_pubkey: Option<[u8; 32]>,
818        stream_kem_recipient: Option<crate::crypto::hybrid_kem::RecipientPublic>,
819        jwt: Option<String>,
820        delegated_bearer: Option<String>,
821        service_domain: Option<&str>,
822        method_discriminator: Option<u16>,
823    ) -> Result<(Vec<u8>, Option<PendingResponse>)> {
824        // Centralize the guard at sealing so every call variant uses exactly
825        // one fresh fetch and keeps its binding local (including concurrent calls).
826        let refreshed = match &self.pre_seal_guard {
827            Some(guard) => guard.current_browser_binding().await?,
828            None => None,
829        };
830        if let Some(current) = &refreshed {
831            let original = self.browser_provisioning_binding.as_ref().ok_or_else(|| {
832                anyhow::anyhow!("fresh browser binding has no immutable client anchor")
833            })?;
834            let mut stable = current.clone();
835            stable.expires_at_unix_ms = original.expires_at_unix_ms;
836            anyhow::ensure!(
837                stable == *original,
838                "fresh browser binding changed client anchor"
839            );
840            current.validate_shape()?;
841            anyhow::ensure!(
842                current.expires_at_unix_ms > chrono::Utc::now().timestamp_millis(),
843                "fresh browser binding expired before seal"
844            );
845        }
846        let browser_binding = refreshed
847            .as_ref()
848            .or(self.browser_provisioning_binding.as_ref());
849        let inferred_method = if browser_binding.is_some() && method_discriminator.is_none() {
850            Some(crate::browser_provisioning::canonical_method_discriminator(
851                &payload,
852            )?)
853        } else {
854            None
855        };
856        let service_domain =
857            service_domain.or_else(|| browser_binding.map(|binding| binding.service_name.as_str()));
858        let method_discriminator = method_discriminator.or(inferred_method);
859        let mut envelope = RequestEnvelope::new(payload);
860        envelope.request_id = request_id;
861        if let Some(token) = jwt {
862            envelope = envelope.with_jwt_token(token);
863        }
864        if let Some(bearer) = delegated_bearer {
865            envelope = envelope.with_delegation_token(bearer);
866        }
867        if let Some(key) = ephemeral_pubkey {
868            envelope = envelope.with_client_dh_public(key);
869        }
870        if let Some(recipient) = stream_kem_recipient {
871            envelope = envelope.with_client_kem_public(recipient)?;
872        }
873        if let Some(service_domain) = service_domain {
874            envelope = envelope.with_service_domain(service_domain)?;
875        }
876        // The browser carrier adds an authenticated provisioning transcript
877        // around the application body. Dispatch removes that wrapper before
878        // comparing proof claim -70003 to the decoded Cap'n Proto request.
879        let proof_body = self
880            .federate_proof_provider
881            .as_ref()
882            .map(|_| envelope.payload.clone());
883        if let Some(binding) = browser_binding {
884            let service_domain = service_domain.ok_or_else(|| {
885                anyhow::anyhow!("browser request extension requires a canonical service domain")
886            })?;
887            let method_discriminator = method_discriminator.ok_or_else(|| {
888                anyhow::anyhow!(
889                    "provisioned browser request requires an explicit generated method identifier"
890                )
891            })?;
892            envelope.payload = crate::browser_provisioning::bind_request_payload(
893                binding,
894                request_id,
895                service_domain,
896                method_discriminator,
897                &envelope.payload,
898            )?;
899        }
900
901        let (pending, encrypted_envelope) = if self.transport.forbids_cleartext_envelope() {
902            let service_domain = service_domain.ok_or_else(|| {
903                anyhow::anyhow!(
904                    "network request has no canonical service domain; use a generated client or explicit service-bound call"
905                )
906            })?;
907            crate::envelope::validate_service_domain(service_domain)?;
908            let server = self.server_verifying_key.as_ref().ok_or_else(|| {
909                anyhow::anyhow!(
910                    "transport forbids cleartext envelopes but no server verifying key is pinned; refusing to choose a #mesh-kem recipient"
911                )
912            })?;
913            let kem_store = self.request_kem_store.as_ref().ok_or_else(|| {
914                anyhow::anyhow!(
915                    "transport forbids cleartext envelopes but no #mesh-kem trust store is configured; refusing cleartext downgrade"
916                )
917            })?;
918            let recipient = kem_store
919                .kem_recipient_for(&server.to_bytes())
920                .ok_or_else(|| {
921                    anyhow::anyhow!(
922                        "transport forbids cleartext envelopes but server {} has no anchored #mesh-kem recipient key",
923                        hex::encode(server.to_bytes())
924                    )
925                })?;
926            let keypair = crate::crypto::hybrid_kem::generate_recipient(
927                crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768,
928            )?;
929            let public = keypair.public();
930            envelope = envelope.with_response_kem_recipient(public.clone());
931            if let Some(provider) = &self.federate_proof_provider {
932                let body = proof_body.as_deref().ok_or_else(|| {
933                    anyhow::anyhow!("Federate proof lost the original Cap'n Proto body")
934                })?;
935                let proof = provider.proof_for(&envelope, body).await?;
936                envelope = envelope.with_proof_cwt(proof);
937            }
938            // This unverified subject inspection only selects extra proof
939            // emission; it grants no authority. Policy verifies the credential
940            // and holder independently. User delegation remains unchanged.
941            if envelope.delegation_token.is_none()
942                && envelope
943                    .jwt_token()
944                    .and_then(|token| crate::auth::decode_unverified(token).ok())
945                    .is_some_and(|claims| claims.sub.starts_with("service:"))
946            {
947                envelope.authorization_witness =
948                    Some(crate::authorization_witness::sign(&envelope, &self.signer).await?);
949            }
950            let pending = Some(PendingResponse {
951                request_id,
952                request_iat: envelope.iat,
953                request_nonce: envelope.nonce,
954                server_identity: server.to_bytes(),
955                recipient_public: public,
956                service_domain: service_domain.to_owned(),
957                secret: ResponseRecipientSecret {
958                    keypair,
959                    #[cfg(test)]
960                    drop_probe: self.response_secret_drop_probe.clone(),
961                },
962            });
963            let sealed = Some(crate::envelope::seal_request_envelope(
964                &envelope, &recipient,
965            )?);
966            (pending, sealed)
967        } else {
968            if let Some(provider) = &self.federate_proof_provider {
969                let body = proof_body.as_deref().ok_or_else(|| {
970                    anyhow::anyhow!("Federate proof lost the original Cap'n Proto body")
971                })?;
972                let proof = provider.proof_for(&envelope, body).await?;
973                envelope = envelope.with_proof_cwt(proof);
974            }
975            (None, None)
976        };
977
978        let canonical = envelope.to_bytes();
979        let ed_pubkey = self.signer.pubkey();
980        let signing_data: &[u8] = encrypted_envelope.as_deref().unwrap_or(&canonical);
981
982        let pq_kid = self.signer.pq_pubkey().ok_or_else(|| {
983            anyhow::anyhow!(
984                "mandatory Hybrid suite requires an ML-DSA-65 signer key; refusing request"
985            )
986        })?;
987
988        // Raw EdDSA signature (sig/cnf) retained for signer-pubkey advertisement
989        // + the JWT cnf key-binding path.
990        let signature = self.signer.sign(signing_data).await?;
991
992        // Build the COSE composite (M3 #152) by signing each entry's
993        // Sig_structure out-of-band via the (possibly async/WASM) Signer.
994        let aad = crate::crypto::cose_sign1::build_external_aad(
995            crate::envelope::ENVELOPE_SCHEMA_ID,
996            crate::envelope::REQUEST_ENVELOPE_TYPE_ID,
997        );
998        // Nested SNS composite: sign the inner EdDSA layer first, then sign the
999        // outer ML-DSA-65 layer over `canonical ‖ inner_eddsa_signature` so the
1000        // inner signature is bound into the outer (Strong-Non-Separable).
1001        //
1002        // The inner EdDSA layer always binds the pinned hybrid-composite alg-id
1003        // into its AAD (#278). There is no classical request construction path.
1004        //
1005        // The inner layer also commits to the ML-DSA-65 key above it, so a
1006        // captured inner layer cannot be re-used under a different outer key.
1007        // This is what lets a server record this client's PQ key at first
1008        // contact on the strength of the Ed25519 signature.
1009        let ed_kid = ed_pubkey.to_vec();
1010        let ed_tbs = crate::crypto::cose_sign::inner_tbs_pq_bound(
1011            ed_kid.clone(),
1012            &pq_kid,
1013            signing_data,
1014            &aad,
1015        );
1016        let ed_sig = self.signer.sign(&ed_tbs).await?.to_vec();
1017
1018        let pq_tbs =
1019            crate::crypto::cose_sign::outer_tbs(pq_kid.clone(), signing_data, &ed_sig, &aad);
1020        let pq_sig = self.signer.pq_sign(&pq_tbs).await?.ok_or_else(|| {
1021            anyhow::anyhow!(
1022                "signer exposes a PQ public key but pq_sign() returned no signature; \
1023                 refusing to emit an incomplete mandatory Hybrid composite"
1024            )
1025        })?;
1026        let cose = crate::crypto::cose_sign::assemble_composite_nested_pq_bound(
1027            (ed_kid, ed_sig),
1028            (pq_kid, pq_sig),
1029        )?;
1030
1031        let signed = SignedEnvelope {
1032            envelope,
1033            sig: signature,
1034            cnf: ed_pubkey,
1035            encrypted_envelope,
1036            client_ephemeral_public: None,
1037            cose,
1038            policy: crate::crypto::CryptoPolicy::Hybrid,
1039            pq_kem_ciphertext: None,
1040        };
1041
1042        let mut message = capnp::message::Builder::new_default();
1043        {
1044            let mut builder = message.init_root::<crate::common_capnp::signed_envelope::Builder>();
1045            signed.write_to(&mut builder);
1046        }
1047        let mut bytes = Vec::new();
1048        capnp::serialize::write_message(&mut bytes, &message)?;
1049        // Async proof/sign callbacks may consume the remainder of the fetched
1050        // projection's lifetime. Never send a binding which expired while sealing.
1051        if let Some(current) = &refreshed {
1052            anyhow::ensure!(
1053                current.expires_at_unix_ms > chrono::Utc::now().timestamp_millis(),
1054                "fresh browser binding expired during seal"
1055            );
1056        }
1057        Ok((bytes, pending))
1058    }
1059
1060    /// Calculate timeout, defaulting to 30s.
1061    fn calculate_timeout(&self) -> Option<i32> {
1062        // JWT is opaque — no client-side expiry capping.
1063        // Server enforces JWT expiry on its side.
1064        Some(30_000)
1065    }
1066
1067    /// Open a verified streaming subscription.
1068    ///
1069    /// Generates an ephemeral keypair, sends the streaming request,
1070    /// performs ECDH + key derivation, subscribes to the data topic,
1071    /// opens the ctrl channel, and creates a verified StreamHandle.
1072    ///
1073    /// All crypto happens in Rust — the caller just gets a handle
1074    /// that yields verified payloads.
1075    #[cfg(not(feature = "fips"))]
1076    pub async fn open_stream(&self, payload: Vec<u8>) -> Result<StreamHandleImpl<T>> {
1077        use crate::crypto::generate_ephemeral_keypair;
1078
1079        let (secret, public) = generate_ephemeral_keypair();
1080        let pub_bytes = public.to_bytes();
1081
1082        // Send streaming request via signed envelope
1083        let response = self.call_streaming(payload, pub_bytes).await?;
1084
1085        // Parse StreamInfo from response
1086        let stream_info = parse_stream_info(&response)?;
1087
1088        // Full streaming setup via Transport
1089        let secret_bytes = secret.scalar().to_bytes();
1090        StreamHandleImpl::open(&self.transport, stream_info, &secret_bytes, &pub_bytes).await
1091    }
1092
1093    /// Open a generated verified stream bound to its canonical service and method.
1094    #[cfg(not(feature = "fips"))]
1095    pub async fn open_stream_for_service_with_method(
1096        &self,
1097        service_domain: &str,
1098        method_discriminator: u16,
1099        payload: Vec<u8>,
1100    ) -> Result<StreamHandleImpl<T>> {
1101        use crate::crypto::generate_ephemeral_keypair;
1102
1103        let (secret, public) = generate_ephemeral_keypair();
1104        let pub_bytes = public.to_bytes();
1105        let response = self
1106            .call_streaming_for_service_with_method(
1107                service_domain,
1108                method_discriminator,
1109                payload,
1110                pub_bytes,
1111            )
1112            .await?;
1113        let stream_info = parse_stream_info(&response)?;
1114        let secret_bytes = secret.scalar().to_bytes();
1115        StreamHandleImpl::open(&self.transport, stream_info, &secret_bytes, &pub_bytes).await
1116    }
1117
1118    /// Open a verified streaming subscription with per-call authentication options.
1119    ///
1120    /// Same as `open_stream` but passes per-call JWT through the streaming
1121    /// request envelope. Used by WASM client where JWT is set post-construction.
1122    #[cfg(not(feature = "fips"))]
1123    pub async fn open_stream_with_options(
1124        &self,
1125        payload: Vec<u8>,
1126        options: CallOptions,
1127    ) -> Result<StreamHandleImpl<T>> {
1128        use crate::crypto::generate_ephemeral_keypair;
1129
1130        let (secret, public) = generate_ephemeral_keypair();
1131        let pub_bytes = public.to_bytes();
1132
1133        let response = self
1134            .call_streaming_with_options(payload, pub_bytes, options)
1135            .await?;
1136        let stream_info = parse_stream_info(&response)?;
1137
1138        let secret_bytes = secret.scalar().to_bytes();
1139        StreamHandleImpl::open(&self.transport, stream_info, &secret_bytes, &pub_bytes).await
1140    }
1141    /// Open an option-bearing generated stream bound to its canonical service and method.
1142    #[cfg(not(feature = "fips"))]
1143    pub async fn open_stream_with_options_for_service_with_method(
1144        &self,
1145        service_domain: &str,
1146        method_discriminator: u16,
1147        payload: Vec<u8>,
1148        options: CallOptions,
1149    ) -> Result<StreamHandleImpl<T>> {
1150        use crate::crypto::generate_ephemeral_keypair;
1151
1152        let (secret, public) = generate_ephemeral_keypair();
1153        let pub_bytes = public.to_bytes();
1154        let response = self
1155            .call_streaming_with_options_for_service_with_method(
1156                service_domain,
1157                method_discriminator,
1158                payload,
1159                pub_bytes,
1160                options,
1161            )
1162            .await?;
1163        let stream_info = parse_stream_info(&response)?;
1164        let secret_bytes = secret.scalar().to_bytes();
1165        StreamHandleImpl::open(&self.transport, stream_info, &secret_bytes, &pub_bytes).await
1166    }
1167
1168    /// Open a verified stream from pre-parsed StreamInfo + ephemeral keys.
1169    ///
1170    /// Use when the streaming RPC was already sent (e.g., via dispatch) and
1171    /// you have the StreamInfo + ephemeral keypair. Skips the send step.
1172    #[cfg(not(feature = "fips"))]
1173    pub async fn open_stream_from_info(
1174        &self,
1175        stream_info: crate::stream_info::StreamInfo,
1176        client_secret: &[u8; 32],
1177        client_pubkey: &[u8; 32],
1178    ) -> Result<StreamHandleImpl<T>> {
1179        StreamHandleImpl::open(&self.transport, stream_info, client_secret, client_pubkey).await
1180    }
1181}
1182
1183/// Parse StreamInfo from Cap'n Proto response bytes.
1184fn parse_stream_info(bytes: &[u8]) -> Result<crate::stream_info::StreamInfo> {
1185    // Borrowing (zero-copy) reader: the capnp `Reader` references `bytes` directly.
1186    let mut slice: &[u8] = bytes;
1187    let reader = capnp::serialize::read_message_from_flat_slice(
1188        &mut slice,
1189        capnp::message::ReaderOptions::default(),
1190    )?;
1191    // StreamInfo may be nested inside a service response variant.
1192    // Try direct parse first (for portable client path).
1193    let si_reader = reader.get_root::<crate::streaming_capnp::stream_info::Reader>()?;
1194    crate::stream_info::StreamInfo::read_from(si_reader)
1195}
1196
1197// ============================================================================
1198// Object-safe trait for generated portable clients
1199// ============================================================================
1200
1201/// Object-safe RPC client trait for dynamic dispatch.
1202///
1203/// Generated portable clients use `Arc<dyn RpcClient>` so they work
1204/// with any `RpcClientImpl<S, T>` regardless of concrete signer/transport.
1205#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
1206#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
1207pub trait RpcClient: Send + Sync {
1208    /// Send a request and return the verified response payload.
1209    async fn call(&self, payload: Vec<u8>) -> Result<Vec<u8>>;
1210
1211    /// Send a request bound to a canonical destination service.
1212    async fn call_for_service(&self, service_domain: &str, payload: Vec<u8>) -> Result<Vec<u8>>;
1213
1214    /// Send a generated request with an explicit canonical schema method id.
1215    async fn call_for_service_with_method(
1216        &self,
1217        service_domain: &str,
1218        method_discriminator: u16,
1219        payload: Vec<u8>,
1220    ) -> Result<Vec<u8>>;
1221
1222    /// Send a request with per-call authentication options.
1223    ///
1224    /// Uses `options.jwt` if provided, otherwise falls back to the client's
1225    /// default JWT. Includes `options.delegated_bearer` in the envelope.
1226    async fn call_with_options(&self, payload: Vec<u8>, options: CallOptions) -> Result<Vec<u8>>;
1227
1228    /// Send an option-bearing request bound to a canonical destination.
1229    async fn call_with_options_for_service(
1230        &self,
1231        service_domain: &str,
1232        payload: Vec<u8>,
1233        options: CallOptions,
1234    ) -> Result<Vec<u8>>;
1235    async fn call_with_options_for_service_with_method(
1236        &self,
1237        service_domain: &str,
1238        method_discriminator: u16,
1239        payload: Vec<u8>,
1240        options: CallOptions,
1241    ) -> Result<Vec<u8>> {
1242        anyhow::ensure!(
1243            options.jwt.is_none() && options.delegated_bearer.is_none(),
1244            "this RPC client does not support method-bound call options"
1245        );
1246        self.call_for_service_with_method(service_domain, method_discriminator, payload)
1247            .await
1248    }
1249
1250    /// Send a streaming request with ephemeral DH pubkey.
1251    async fn call_streaming(&self, payload: Vec<u8>, ephemeral_pubkey: [u8; 32])
1252        -> Result<Vec<u8>>;
1253
1254    /// Send a streaming setup request bound to a canonical destination.
1255    async fn call_streaming_for_service(
1256        &self,
1257        service_domain: &str,
1258        payload: Vec<u8>,
1259        ephemeral_pubkey: [u8; 32],
1260    ) -> Result<Vec<u8>>;
1261    async fn call_streaming_with_options_for_service(
1262        &self,
1263        service_domain: &str,
1264        payload: Vec<u8>,
1265        ephemeral_pubkey: [u8; 32],
1266        options: CallOptions,
1267    ) -> Result<Vec<u8>> {
1268        anyhow::ensure!(
1269            options.jwt.is_none() && options.delegated_bearer.is_none(),
1270            "this RPC client does not support streaming call options"
1271        );
1272        self.call_streaming_for_service(service_domain, payload, ephemeral_pubkey)
1273            .await
1274    }
1275
1276    /// Send a generated streaming request with an explicit schema method id.
1277    async fn call_streaming_for_service_with_method(
1278        &self,
1279        service_domain: &str,
1280        method_discriminator: u16,
1281        payload: Vec<u8>,
1282        ephemeral_pubkey: [u8; 32],
1283    ) -> Result<Vec<u8>>;
1284    async fn call_streaming_with_options_for_service_with_method(
1285        &self,
1286        service_domain: &str,
1287        method_discriminator: u16,
1288        payload: Vec<u8>,
1289        ephemeral_pubkey: [u8; 32],
1290        options: CallOptions,
1291    ) -> Result<Vec<u8>> {
1292        anyhow::ensure!(
1293            options.jwt.is_none() && options.delegated_bearer.is_none(),
1294            "this RPC client does not support method-bound streaming call options"
1295        );
1296        self.call_streaming_for_service_with_method(
1297            service_domain,
1298            method_discriminator,
1299            payload,
1300            ephemeral_pubkey,
1301        )
1302        .await
1303    }
1304
1305    /// Open a verified streaming subscription.
1306    async fn open_stream(&self, payload: Vec<u8>) -> Result<Box<dyn StreamHandle>>;
1307
1308    /// Open a verified stream from pre-parsed StreamInfo + ephemeral keys.
1309    async fn open_stream_from_info(
1310        &self,
1311        stream_info: crate::stream_info::StreamInfo,
1312        client_secret: [u8; 32],
1313        client_pubkey: [u8; 32],
1314    ) -> Result<Box<dyn StreamHandle>>;
1315
1316    /// Get the next request ID.
1317    fn next_id(&self) -> u64;
1318}
1319
1320/// Application-supplied construction seam for generated service clients.
1321///
1322/// The contract/client crates depend only on this trait; deployment-specific
1323/// resolver authority (for example, checkpoint-backed Discovery) implements it
1324/// in the service/application crate. This keeps production endpoint discovery
1325/// out of permissively licensed SDK packages while still allowing callers to
1326/// construct typed clients from a single provider.
1327pub trait RpcClientProvider: Send + Sync {
1328    /// Build an object-safe RPC client bound to `service_name`.
1329    fn rpc_client(
1330        &self,
1331        service_name: &str,
1332        signing_key: crate::crypto::SigningKey,
1333        token: Option<String>,
1334    ) -> Result<Arc<dyn RpcClient>>;
1335}
1336
1337/// Blanket impl: any `RpcClientImpl<S, T>` satisfies `RpcClient`.
1338#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
1339#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
1340impl<S: Signer, T: Transport + 'static> RpcClient for RpcClientImpl<S, T> {
1341    async fn call(&self, payload: Vec<u8>) -> Result<Vec<u8>> {
1342        RpcClientImpl::call(self, payload).await
1343    }
1344
1345    async fn call_for_service(&self, service_domain: &str, payload: Vec<u8>) -> Result<Vec<u8>> {
1346        RpcClientImpl::call_for_service(self, service_domain, payload).await
1347    }
1348
1349    async fn call_for_service_with_method(
1350        &self,
1351        service_domain: &str,
1352        method_discriminator: u16,
1353        payload: Vec<u8>,
1354    ) -> Result<Vec<u8>> {
1355        RpcClientImpl::call_for_service_with_method(
1356            self,
1357            service_domain,
1358            method_discriminator,
1359            payload,
1360        )
1361        .await
1362    }
1363
1364    async fn call_with_options(&self, payload: Vec<u8>, options: CallOptions) -> Result<Vec<u8>> {
1365        RpcClientImpl::call_with_options(self, payload, options).await
1366    }
1367
1368    async fn call_with_options_for_service(
1369        &self,
1370        service_domain: &str,
1371        payload: Vec<u8>,
1372        options: CallOptions,
1373    ) -> Result<Vec<u8>> {
1374        RpcClientImpl::call_with_options_for_service(self, service_domain, payload, options).await
1375    }
1376    async fn call_with_options_for_service_with_method(
1377        &self,
1378        service_domain: &str,
1379        method_discriminator: u16,
1380        payload: Vec<u8>,
1381        options: CallOptions,
1382    ) -> Result<Vec<u8>> {
1383        RpcClientImpl::call_with_options_for_service_with_method(
1384            self,
1385            service_domain,
1386            method_discriminator,
1387            payload,
1388            options,
1389        )
1390        .await
1391    }
1392
1393    async fn call_streaming(
1394        &self,
1395        payload: Vec<u8>,
1396        ephemeral_pubkey: [u8; 32],
1397    ) -> Result<Vec<u8>> {
1398        RpcClientImpl::call_streaming(self, payload, ephemeral_pubkey).await
1399    }
1400
1401    async fn call_streaming_for_service(
1402        &self,
1403        service_domain: &str,
1404        payload: Vec<u8>,
1405        ephemeral_pubkey: [u8; 32],
1406    ) -> Result<Vec<u8>> {
1407        RpcClientImpl::call_streaming_for_service(self, service_domain, payload, ephemeral_pubkey)
1408            .await
1409    }
1410    async fn call_streaming_with_options_for_service(
1411        &self,
1412        service_domain: &str,
1413        payload: Vec<u8>,
1414        ephemeral_pubkey: [u8; 32],
1415        options: CallOptions,
1416    ) -> Result<Vec<u8>> {
1417        RpcClientImpl::call_streaming_with_options_for_service(
1418            self,
1419            service_domain,
1420            payload,
1421            ephemeral_pubkey,
1422            options,
1423        )
1424        .await
1425    }
1426
1427    async fn call_streaming_for_service_with_method(
1428        &self,
1429        service_domain: &str,
1430        method_discriminator: u16,
1431        payload: Vec<u8>,
1432        ephemeral_pubkey: [u8; 32],
1433    ) -> Result<Vec<u8>> {
1434        RpcClientImpl::call_streaming_for_service_with_method(
1435            self,
1436            service_domain,
1437            method_discriminator,
1438            payload,
1439            ephemeral_pubkey,
1440        )
1441        .await
1442    }
1443    async fn call_streaming_with_options_for_service_with_method(
1444        &self,
1445        service_domain: &str,
1446        method_discriminator: u16,
1447        payload: Vec<u8>,
1448        ephemeral_pubkey: [u8; 32],
1449        options: CallOptions,
1450    ) -> Result<Vec<u8>> {
1451        RpcClientImpl::call_streaming_with_options_for_service_with_method(
1452            self,
1453            service_domain,
1454            method_discriminator,
1455            payload,
1456            ephemeral_pubkey,
1457            options,
1458        )
1459        .await
1460    }
1461
1462    #[cfg(not(feature = "fips"))]
1463    async fn open_stream(&self, payload: Vec<u8>) -> Result<Box<dyn StreamHandle>> {
1464        let handle = RpcClientImpl::open_stream(self, payload).await?;
1465        Ok(Box::new(handle))
1466    }
1467
1468    #[cfg(feature = "fips")]
1469    async fn open_stream(&self, _payload: Vec<u8>) -> Result<Box<dyn StreamHandle>> {
1470        anyhow::bail!("streaming not available under FIPS")
1471    }
1472
1473    #[cfg(not(feature = "fips"))]
1474    async fn open_stream_from_info(
1475        &self,
1476        stream_info: crate::stream_info::StreamInfo,
1477        client_secret: [u8; 32],
1478        client_pubkey: [u8; 32],
1479    ) -> Result<Box<dyn StreamHandle>> {
1480        let handle =
1481            RpcClientImpl::open_stream_from_info(self, stream_info, &client_secret, &client_pubkey)
1482                .await?;
1483        Ok(Box::new(handle))
1484    }
1485
1486    #[cfg(feature = "fips")]
1487    async fn open_stream_from_info(
1488        &self,
1489        _stream_info: crate::stream_info::StreamInfo,
1490        _client_secret: [u8; 32],
1491        _client_pubkey: [u8; 32],
1492    ) -> Result<Box<dyn StreamHandle>> {
1493        anyhow::bail!("streaming not available under FIPS")
1494    }
1495
1496    fn next_id(&self) -> u64 {
1497        RpcClientImpl::next_id(self)
1498    }
1499}
1500
1501#[cfg(all(test, not(target_arch = "wasm32")))]
1502#[allow(clippy::unwrap_used, clippy::expect_used)]
1503mod request_kem_tests {
1504    //! Coverage for request KEM-store plumbing and browser-dial defenses.
1505    //!
1506    //! `dial_wasm` is `#![cfg(target_arch = "wasm32")]`, so native tests cannot
1507    //! invoke its JS signer and WebTransport argument types. The public wasm
1508    //! dial seams now return the provisioning-required error before transport
1509    //! construction; the common-layer tests below retain defense-in-depth
1510    //! coverage for cleartext refusal and encrypted request handling.
1511
1512    use super::*;
1513    use crate::crypto::hybrid_kem::KeyedKemTrustStore;
1514    use crate::crypto::signing::generate_signing_keypair;
1515    use crate::node_identity::derive_mesh_kem_recipient;
1516    use crate::signer::LocalSigner;
1517    use crate::transport::rpc_session::{RpcPendingStream, RpcPublishStub};
1518    use std::sync::atomic::{AtomicBool, AtomicU8, AtomicUsize, Ordering};
1519    use tokio::sync::{oneshot, Mutex, Notify};
1520
1521    struct TestFederateProofProvider {
1522        seen: Arc<
1523            parking_lot::Mutex<
1524                Option<(
1525                    Vec<u8>,
1526                    crate::proof::recipient_binding::FederateRecipientBinding,
1527                )>,
1528            >,
1529        >,
1530    }
1531
1532    #[async_trait]
1533    impl FederateProofProvider for TestFederateProofProvider {
1534        async fn proof_for(
1535            &self,
1536            envelope: &RequestEnvelope,
1537            capnp_body: &[u8],
1538        ) -> Result<Vec<u8>> {
1539            use crate::proof::{
1540                build::{
1541                    build_authenticated_hybrid_request_proof, AuthenticatedHybridProofSigner,
1542                    AuthenticatedRequestProofInput,
1543                },
1544                recipient_binding::FederateRecipientBinding,
1545            };
1546            let binding = FederateRecipientBinding::from_recipients(
1547                envelope.response_kem_recipient.as_ref(),
1548                envelope.client_kem_public.as_ref(),
1549                envelope.client_dh_public,
1550            )?;
1551            *self.seen.lock() = Some((capnp_body.to_vec(), binding.clone()));
1552            let signer = AuthenticatedHybridProofSigner::new(
1553                ed25519_dalek::SigningKey::from_bytes(&[9; 32]),
1554                b"proof-fixture-ed".to_vec(),
1555                crate::crypto::pq::ml_dsa_sk_from_seed(&[10; 32]),
1556                b"proof-fixture-pq".to_vec(),
1557            )?;
1558            let issued_at = u64::try_from(envelope.iat)?;
1559            build_authenticated_hybrid_request_proof(
1560                &AuthenticatedRequestProofInput {
1561                    service_domain: envelope.service_domain.as_deref().unwrap(),
1562                    credential: envelope.jwt_token().unwrap().as_bytes(),
1563                    issued_at,
1564                    expires_at: issued_at + 30,
1565                    capnp_schema_id: 0xd4d0_f2a1_b3c5_8e67,
1566                    capnp_body,
1567                    response_binding: None,
1568                    federate_recipient_binding: Some(&binding),
1569                },
1570                &signer,
1571            )
1572        }
1573    }
1574
1575    /// A carrier that forbids cleartext envelopes; `send` must never be reached
1576    /// in these tests (they stop at `sign_envelope`).
1577    struct ForbidsCleartextMock;
1578
1579    struct CleartextResponseMock(Vec<u8>);
1580
1581    const LIFECYCLE_SUCCESS: u8 = 0;
1582    const LIFECYCLE_FAIL_SEND: u8 = 1;
1583    const LIFECYCLE_BLOCK: u8 = 2;
1584    const LIFECYCLE_SWAP: u8 = 3;
1585
1586    struct LifecycleState {
1587        behavior: AtomicU8,
1588        recipients: parking_lot::Mutex<Vec<Vec<u8>>>,
1589        auth: parking_lot::Mutex<Vec<(Option<String>, Option<String>)>>,
1590        swap_waiters: Mutex<Vec<(Vec<u8>, oneshot::Sender<Vec<u8>>)>>,
1591        entered: Notify,
1592    }
1593
1594    struct LifecycleTransport {
1595        server_sk: crate::crypto::SigningKey,
1596        state: Arc<LifecycleState>,
1597    }
1598
1599    impl LifecycleTransport {
1600        fn response_for(&self, payload: &[u8]) -> Result<Vec<u8>> {
1601            let mut signed = signed_envelope_from_bytes(payload);
1602            let server_recipient = derive_mesh_kem_recipient(&self.server_sk)?;
1603            signed.decrypt_in_place_mesh_kem(&server_recipient)?;
1604            let request = signed.envelope;
1605            let recipient = request
1606                .response_kem_recipient
1607                .as_ref()
1608                .ok_or_else(|| anyhow::anyhow!("test request omitted response recipient"))?;
1609            let service_domain = request
1610                .service_domain
1611                .as_deref()
1612                .ok_or_else(|| anyhow::anyhow!("test request omitted service domain"))?;
1613            self.state.recipients.lock().push(recipient.encode());
1614            self.state.auth.lock().push((
1615                request.jwt_token().map(str::to_owned),
1616                request.delegation_token.clone(),
1617            ));
1618            let pq_sk = crate::node_identity::derive_mesh_mldsa_key(&self.server_sk);
1619            let response = crate::envelope::ResponseEnvelope::new_signed_encrypted(
1620                request.request_id,
1621                request.payload,
1622                &self.server_sk,
1623                &pq_sk,
1624                recipient,
1625                request.iat,
1626                &request.nonce,
1627                service_domain,
1628            )?;
1629            let mut message = capnp::message::Builder::new_default();
1630            response.write_to(
1631                &mut message.init_root::<crate::common_capnp::response_envelope::Builder>(),
1632            );
1633            let mut bytes = Vec::new();
1634            capnp::serialize::write_message(&mut bytes, &message)?;
1635            Ok(bytes)
1636        }
1637    }
1638
1639    #[async_trait]
1640    impl Transport for LifecycleTransport {
1641        type Sub = RpcPendingStream;
1642        type Pub = RpcPublishStub;
1643
1644        fn forbids_cleartext_envelope(&self) -> bool {
1645            true
1646        }
1647
1648        async fn send(&self, payload: Vec<u8>, _timeout_ms: Option<i32>) -> Result<Vec<u8>> {
1649            let response = self.response_for(&payload)?;
1650            match self.state.behavior.load(Ordering::SeqCst) {
1651                LIFECYCLE_SUCCESS => Ok(response),
1652                LIFECYCLE_FAIL_SEND => anyhow::bail!("controlled send failure"),
1653                LIFECYCLE_BLOCK => {
1654                    self.state.entered.notify_waiters();
1655                    std::future::pending().await
1656                }
1657                LIFECYCLE_SWAP => {
1658                    let (tx, rx) = oneshot::channel();
1659                    let mut waiters = self.state.swap_waiters.lock().await;
1660                    waiters.push((response, tx));
1661                    if waiters.len() == 2 {
1662                        let (second_response, second_tx) = waiters.pop().unwrap();
1663                        let (first_response, first_tx) = waiters.pop().unwrap();
1664                        first_tx
1665                            .send(second_response)
1666                            .map_err(|_| anyhow::anyhow!("first swapped caller was cancelled"))?;
1667                        second_tx
1668                            .send(first_response)
1669                            .map_err(|_| anyhow::anyhow!("second swapped caller was cancelled"))?;
1670                    }
1671                    drop(waiters);
1672                    rx.await
1673                        .map_err(|_| anyhow::anyhow!("swap response channel closed"))
1674                }
1675                other => anyhow::bail!("unknown lifecycle behavior {other}"),
1676            }
1677        }
1678
1679        async fn subscribe(&self, _topic: &[u8]) -> Result<Self::Sub> {
1680            Ok(futures::stream::pending())
1681        }
1682
1683        async fn publish(&self, _topic: &[u8]) -> Result<Self::Pub> {
1684            Ok(RpcPublishStub)
1685        }
1686    }
1687
1688    fn lifecycle_client() -> (
1689        Arc<RpcClientImpl<LocalSigner, LifecycleTransport>>,
1690        Arc<LifecycleState>,
1691        Arc<AtomicUsize>,
1692    ) {
1693        lifecycle_client_with_browser_binding(None)
1694    }
1695
1696    fn lifecycle_client_with_browser_binding(
1697        browser_binding: Option<crate::browser_provisioning::BrowserRequestBinding>,
1698    ) -> (
1699        Arc<RpcClientImpl<LocalSigner, LifecycleTransport>>,
1700        Arc<LifecycleState>,
1701        Arc<AtomicUsize>,
1702    ) {
1703        lifecycle_client_with_options(browser_binding, None)
1704    }
1705
1706    fn lifecycle_client_with_options(
1707        browser_binding: Option<crate::browser_provisioning::BrowserRequestBinding>,
1708        default_jwt: Option<String>,
1709    ) -> (
1710        Arc<RpcClientImpl<LocalSigner, LifecycleTransport>>,
1711        Arc<LifecycleState>,
1712        Arc<AtomicUsize>,
1713    ) {
1714        let (server_sk, server_vk) = generate_signing_keypair();
1715        let (client_sk, _client_vk) = generate_signing_keypair();
1716        let mut kem_store = KeyedKemTrustStore::new();
1717        kem_store.bind(
1718            server_vk.to_bytes(),
1719            derive_mesh_kem_recipient(&server_sk).unwrap().public(),
1720        );
1721        let pq_sk = crate::node_identity::derive_mesh_mldsa_key(&server_sk);
1722        let pq_vk = crate::crypto::pq::ml_dsa_vk_from_bytes(
1723            &crate::crypto::pq::ml_dsa_sk_to_vk_bytes(&pq_sk),
1724        )
1725        .unwrap();
1726        let mut pq_store = crate::envelope::KeyedPqTrustStore::new();
1727        pq_store.bind(server_vk.to_bytes(), &pq_vk);
1728        let state = Arc::new(LifecycleState {
1729            behavior: AtomicU8::new(LIFECYCLE_SUCCESS),
1730            recipients: parking_lot::Mutex::new(Vec::new()),
1731            auth: parking_lot::Mutex::new(Vec::new()),
1732            swap_waiters: Mutex::new(Vec::new()),
1733            entered: Notify::new(),
1734        });
1735        let drops = Arc::new(AtomicUsize::new(0));
1736        let client = RpcClientImpl::new(
1737            LocalSigner::new(client_sk),
1738            LifecycleTransport {
1739                server_sk,
1740                state: Arc::clone(&state),
1741            },
1742            Some(server_vk),
1743        )
1744        .with_request_kem_store(Arc::new(kem_store))
1745        .with_response_pq_store(Arc::new(pq_store))
1746        .with_response_secret_drop_probe(Arc::clone(&drops));
1747        let client = match default_jwt {
1748            Some(token) => client.with_default_jwt(token),
1749            None => client,
1750        };
1751        let client = match browser_binding {
1752            Some(binding) => client
1753                .with_browser_provisioning_binding(binding)
1754                .expect("valid browser binding"),
1755            None => client,
1756        };
1757        (Arc::new(client), state, drops)
1758    }
1759
1760    #[tokio::test]
1761    async fn delegated_bearer_suppresses_pooled_default_jwt() {
1762        let (client, state, _drops) =
1763            lifecycle_client_with_options(None, Some("pooled-default".to_owned()));
1764
1765        client
1766            .call_with_options_for_service(
1767                "model",
1768                b"unary".to_vec(),
1769                CallOptions::new().delegated_bearer("delegated-user"),
1770            )
1771            .await
1772            .expect("delegated unary call");
1773        client
1774            .call_streaming_with_options_for_service(
1775                "model",
1776                b"streaming".to_vec(),
1777                [0x55; 32],
1778                CallOptions::new().delegated_bearer("delegated-user"),
1779            )
1780            .await
1781            .expect("delegated streaming call");
1782
1783        let auth = state.auth.lock();
1784        assert_eq!(auth.len(), 2);
1785        for (jwt, delegated) in auth.iter() {
1786            assert!(jwt.is_none(), "default JWT must not override delegation");
1787            assert_eq!(delegated.as_deref(), Some("delegated-user"));
1788        }
1789    }
1790
1791    #[tokio::test]
1792    async fn explicit_jwt_and_delegated_bearer_are_rejected() {
1793        let (client, state, _drops) = lifecycle_client();
1794        let error = client
1795            .call_with_options_for_service(
1796                "model",
1797                b"payload".to_vec(),
1798                CallOptions::new()
1799                    .jwt("direct-user")
1800                    .delegated_bearer("delegated-user"),
1801            )
1802            .await
1803            .expect_err("ambiguous principal selection must fail");
1804        assert!(
1805            error
1806                .to_string()
1807                .contains("both a direct JWT and a delegated bearer"),
1808            "unexpected error: {error}"
1809        );
1810        assert!(
1811            state.auth.lock().is_empty(),
1812            "ambiguous request must not reach the transport"
1813        );
1814    }
1815
1816    #[async_trait]
1817    impl Transport for ForbidsCleartextMock {
1818        type Sub = RpcPendingStream;
1819        type Pub = RpcPublishStub;
1820
1821        fn forbids_cleartext_envelope(&self) -> bool {
1822            true
1823        }
1824
1825        async fn send(&self, _payload: Vec<u8>, _timeout_ms: Option<i32>) -> Result<Vec<u8>> {
1826            anyhow::bail!("mock transport: send must not be reached in sign_envelope tests")
1827        }
1828
1829        async fn subscribe(&self, _topic: &[u8]) -> Result<Self::Sub> {
1830            anyhow::bail!("mock transport: no subscribe")
1831        }
1832
1833        async fn publish(&self, _topic: &[u8]) -> Result<Self::Pub> {
1834            anyhow::bail!("mock transport: no publish")
1835        }
1836    }
1837
1838    #[async_trait]
1839    impl Transport for CleartextResponseMock {
1840        type Sub = RpcPendingStream;
1841        type Pub = RpcPublishStub;
1842
1843        fn forbids_cleartext_envelope(&self) -> bool {
1844            true
1845        }
1846
1847        async fn send(&self, _payload: Vec<u8>, _timeout_ms: Option<i32>) -> Result<Vec<u8>> {
1848            Ok(self.0.clone())
1849        }
1850
1851        async fn subscribe(&self, _topic: &[u8]) -> Result<Self::Sub> {
1852            anyhow::bail!("unused")
1853        }
1854
1855        async fn publish(&self, _topic: &[u8]) -> Result<Self::Pub> {
1856            anyhow::bail!("unused")
1857        }
1858    }
1859
1860    fn response_wire(response: &crate::envelope::ResponseEnvelope) -> Vec<u8> {
1861        let mut message = capnp::message::Builder::new_default();
1862        let mut builder = message.init_root::<crate::common_capnp::response_envelope::Builder>();
1863        response.write_to(&mut builder);
1864        let mut bytes = Vec::new();
1865        capnp::serialize::write_message(&mut bytes, &message).unwrap();
1866        bytes
1867    }
1868
1869    /// A carrier that records whether `send` was ever reached, with a
1870    /// configurable cleartext-forbidding classification. Used by the full
1871    /// `RpcClient::call()` sentinel tests (ported from #1032, adapted to
1872    /// #1036's `forbids_cleartext_envelope` model — no WarnOnly / runtime
1873    /// downgrade). If the fail-closed guard works, a forbidding-carrier client
1874    /// with no KEM store must error WITHOUT `send` being called.
1875    struct SentinelTransport {
1876        sent: Arc<AtomicBool>,
1877        forbids: bool,
1878    }
1879
1880    #[async_trait]
1881    impl Transport for SentinelTransport {
1882        type Sub = RpcPendingStream;
1883        type Pub = RpcPublishStub;
1884
1885        fn forbids_cleartext_envelope(&self) -> bool {
1886            self.forbids
1887        }
1888
1889        async fn send(&self, _payload: Vec<u8>, _timeout_ms: Option<i32>) -> Result<Vec<u8>> {
1890            self.sent.store(true, Ordering::SeqCst);
1891            // Bogus empty reply: response unwrap fails after this, but the tests
1892            // assert on `sent` to be unambiguous about WHERE the failure occurs.
1893            Ok(Vec::new())
1894        }
1895
1896        async fn subscribe(&self, _topic: &[u8]) -> Result<Self::Sub> {
1897            Ok(futures::stream::pending())
1898        }
1899
1900        async fn publish(&self, _topic: &[u8]) -> Result<Self::Pub> {
1901            Ok(RpcPublishStub)
1902        }
1903    }
1904
1905    fn signed_envelope_from_bytes(bytes: &[u8]) -> SignedEnvelope {
1906        let reader = capnp::serialize::read_message(
1907            &mut std::io::Cursor::new(bytes),
1908            capnp::message::ReaderOptions::new(),
1909        )
1910        .expect("read signed envelope");
1911        let sr = reader
1912            .get_root::<crate::common_capnp::signed_envelope::Reader>()
1913            .expect("signed envelope root");
1914        SignedEnvelope::read_from(sr).expect("decode signed envelope")
1915    }
1916
1917    /// `None` store on a cleartext-forbidding carrier MUST fail closed — never
1918    /// a cleartext downgrade. Public wasm dial seams now reject earlier, before
1919    /// transport construction; this remains common-layer defense in depth.
1920    #[tokio::test]
1921    async fn cleartext_forbidding_carrier_without_kem_store_fails_closed() {
1922        let (_server_sk, server_vk) = generate_signing_keypair();
1923        let (client_sk, _client_vk) = generate_signing_keypair();
1924
1925        // Pinned server key present, but NO request KEM store (the `None` arm).
1926        let rpc = RpcClientImpl::new(
1927            LocalSigner::new(client_sk),
1928            ForbidsCleartextMock,
1929            Some(server_vk),
1930        );
1931
1932        let err = rpc
1933            .sign_envelope(
1934                1,
1935                b"payload".to_vec(),
1936                None,
1937                None,
1938                None,
1939                None,
1940                Some("test-service"),
1941                None,
1942            )
1943            .await
1944            .expect_err("must fail closed without a #mesh-kem store");
1945        assert!(
1946            err.to_string().contains("mesh-kem trust"),
1947            "expected fail-closed on missing KEM store, got: {err}"
1948        );
1949    }
1950
1951    /// An anchored KEM store on a cleartext-forbidding carrier MUST encrypt.
1952    /// This is common-layer defense in depth; public wasm dial seams cannot
1953    /// construct an unprovisioned client even when callers supply stores.
1954    #[tokio::test]
1955    async fn cleartext_forbidding_carrier_with_kem_store_encrypts() {
1956        let (server_sk, server_vk) = generate_signing_keypair();
1957        let (client_sk, _client_vk) = generate_signing_keypair();
1958
1959        // Anchor the server's #mesh-kem recipient key (out-of-band binding).
1960        let mut kem_store = KeyedKemTrustStore::new();
1961        kem_store.bind(
1962            server_vk.to_bytes(),
1963            derive_mesh_kem_recipient(&server_sk).unwrap().public(),
1964        );
1965
1966        let rpc = RpcClientImpl::new(
1967            LocalSigner::new(client_sk),
1968            ForbidsCleartextMock,
1969            Some(server_vk),
1970        )
1971        .with_request_kem_store(Arc::new(kem_store));
1972
1973        let (bytes, pending) = rpc
1974            .sign_envelope(
1975                1,
1976                b"payload".to_vec(),
1977                None,
1978                None,
1979                None,
1980                None,
1981                Some("test-service"),
1982                None,
1983            )
1984            .await
1985            .expect("forwarded store must seal the envelope");
1986        assert!(
1987            pending.is_some(),
1988            "network call must retain a response secret"
1989        );
1990        let signed = signed_envelope_from_bytes(&bytes);
1991        assert!(
1992            signed.is_encrypted(),
1993            "forwarded #mesh-kem store must yield an encrypted_envelope"
1994        );
1995        // The redacted outer payload must not carry the cleartext.
1996        assert!(
1997            !bytes.windows(b"payload".len()).any(|w| w == b"payload"),
1998            "cleartext payload must not appear on the wire"
1999        );
2000    }
2001
2002    #[tokio::test]
2003    async fn federate_proof_commits_final_browser_body_and_actual_response_recipient() {
2004        let (server_sk, server_vk) = generate_signing_keypair();
2005        let (client_sk, _) = generate_signing_keypair();
2006        let server_recipient = derive_mesh_kem_recipient(&server_sk).unwrap();
2007        let mut kem_store = KeyedKemTrustStore::new();
2008        kem_store.bind(server_vk.to_bytes(), server_recipient.public());
2009        let seen = Arc::new(parking_lot::Mutex::new(None));
2010        let client = RpcClientImpl::new(
2011            LocalSigner::new(client_sk),
2012            ForbidsCleartextMock,
2013            Some(server_vk),
2014        )
2015        .with_request_kem_store(Arc::new(kem_store))
2016        .with_browser_provisioning_binding(browser_test_binding())
2017        .unwrap()
2018        .with_federate_proof_provider(Arc::new(TestFederateProofProvider { seen: seen.clone() }))
2019        .with_default_jwt("fixture.sender.constrained.jwt".into());
2020        let original = browser_capnp_request(7);
2021        let (wire, _) = client
2022            .sign_envelope(
2023                17,
2024                original.clone(),
2025                None,
2026                None,
2027                Some("fixture.sender.constrained.jwt".into()),
2028                None,
2029                Some("model"),
2030                Some(7),
2031            )
2032            .await
2033            .unwrap();
2034        let mut signed = signed_envelope_from_bytes(&wire);
2035        signed.decrypt_in_place_mesh_kem(&server_recipient).unwrap();
2036        let forwarded = signed.envelope;
2037        let proof = crate::proof::parser::ParsedProof::parse_deferred_federate_request(
2038            forwarded.proof_cwt.as_deref().unwrap(),
2039        )
2040        .unwrap();
2041        let (signed_body, binding) = seen.lock().clone().unwrap();
2042        assert_eq!(
2043            signed_body, original,
2044            "proof must sign the application Cap'n Proto body"
2045        );
2046        let (_, recovered) = crate::browser_provisioning::recover_request_payload(
2047            &forwarded.payload,
2048            crate::browser_provisioning::BrowserTranscriptPolicy::Required {
2049                request_id: 17,
2050                service_name: "model",
2051                carrier_profile:
2052                    crate::browser_provisioning::BrowserCarrierProfile::OwnedHybridWebTransport,
2053            },
2054        )
2055        .unwrap();
2056        assert_eq!(proof.claims.capnp_body_bytes, recovered);
2057        assert_ne!(
2058            proof.claims.capnp_body_bytes, forwarded.payload,
2059            "signing the transport framing would fail dispatch's body comparison"
2060        );
2061        assert_eq!(
2062            proof.claims.federate_recipient_binding.as_ref(),
2063            Some(&binding)
2064        );
2065        assert!(binding.matches(forwarded.response_kem_recipient.as_ref(), None, None));
2066        let replacement = crate::crypto::hybrid_kem::generate_recipient(
2067            crate::crypto::hybrid_kem::SuiteId::HyKemX25519MlKem768,
2068        )
2069        .unwrap()
2070        .public();
2071        assert!(
2072            !binding.matches(Some(&replacement), None, None),
2073            "substituting the forwarded recipient must invalidate the signed binding"
2074        );
2075    }
2076
2077    struct FreshBindingGuard {
2078        binding: crate::browser_provisioning::BrowserRequestBinding,
2079        fail: bool,
2080        calls: std::sync::atomic::AtomicUsize,
2081    }
2082
2083    #[async_trait]
2084    impl PreSealGuard for FreshBindingGuard {
2085        async fn ensure_current(&self) -> Result<()> {
2086            anyhow::bail!("fixture must use the single-fetch binding seam")
2087        }
2088
2089        async fn current_browser_binding(
2090            &self,
2091        ) -> Result<Option<crate::browser_provisioning::BrowserRequestBinding>> {
2092            self.calls.fetch_add(1, Ordering::Relaxed);
2093            anyhow::ensure!(!self.fail, "fixture fetch failure");
2094            Ok(Some(self.binding.clone()))
2095        }
2096    }
2097
2098    #[tokio::test]
2099    async fn refreshed_browser_binding_is_sealed_after_original_projection_expires() {
2100        let (server_sk, server_vk) = generate_signing_keypair();
2101        let (client_sk, _) = generate_signing_keypair();
2102        let server_recipient = derive_mesh_kem_recipient(&server_sk).unwrap();
2103        let mut kem_store = KeyedKemTrustStore::new();
2104        kem_store.bind(server_vk.to_bytes(), server_recipient.public());
2105        let mut original = browser_test_binding();
2106        original.expires_at_unix_ms = 1;
2107        let mut current = original.clone();
2108        current.expires_at_unix_ms = chrono::Utc::now().timestamp_millis() + 30_000;
2109        let guard = Arc::new(FreshBindingGuard {
2110            binding: current.clone(),
2111            fail: false,
2112            calls: Default::default(),
2113        });
2114        let mut client = RpcClientImpl::new(
2115            LocalSigner::new(client_sk),
2116            ForbidsCleartextMock,
2117            Some(server_vk),
2118        )
2119        .with_request_kem_store(Arc::new(kem_store))
2120        .with_browser_provisioning_binding(original.clone())
2121        .unwrap()
2122        .with_pre_seal_guard(guard.clone());
2123        let application = browser_capnp_request(7);
2124        let (wire, _) = client
2125            .sign_envelope(
2126                17,
2127                application.clone(),
2128                None,
2129                None,
2130                None,
2131                None,
2132                Some("model"),
2133                Some(7),
2134            )
2135            .await
2136            .unwrap();
2137        assert_eq!(guard.calls.load(Ordering::Relaxed), 1);
2138        let mut signed = signed_envelope_from_bytes(&wire);
2139        signed.decrypt_in_place_mesh_kem(&server_recipient).unwrap();
2140        let (extension, body) = crate::browser_provisioning::recover_request_payload(
2141            &signed.envelope.payload,
2142            crate::browser_provisioning::BrowserTranscriptPolicy::Required {
2143                request_id: 17,
2144                service_name: "model",
2145                carrier_profile:
2146                    crate::browser_provisioning::BrowserCarrierProfile::OwnedHybridWebTransport,
2147            },
2148        )
2149        .unwrap();
2150        assert_eq!(body, application);
2151        assert_eq!(extension.unwrap().binding, current);
2152        assert!(current.expires_at_unix_ms > chrono::Utc::now().timestamp_millis());
2153        assert_eq!(
2154            client.browser_provisioning_binding.as_ref(),
2155            Some(&original)
2156        );
2157        // No fallback to stale binding on network failure, expired fresh data,
2158        // or an attempted authority/key change, even from a faulty guard.
2159        for case in 0..4 {
2160            let mut binding = current.clone();
2161            if case == 1 {
2162                binding.expires_at_unix_ms = 1;
2163            }
2164            if case == 2 {
2165                binding.accepted_state_epoch += 1;
2166            }
2167            if case == 3 {
2168                binding.response_key_id.push_str("-changed");
2169            }
2170            client.pre_seal_guard = Some(Arc::new(FreshBindingGuard {
2171                binding,
2172                fail: case == 0,
2173                calls: Default::default(),
2174            }));
2175            assert!(client
2176                .sign_envelope(
2177                    18,
2178                    application.clone(),
2179                    None,
2180                    None,
2181                    None,
2182                    None,
2183                    Some("model"),
2184                    Some(7)
2185                )
2186                .await
2187                .is_err());
2188        }
2189    }
2190
2191    fn browser_test_binding() -> crate::browser_provisioning::BrowserRequestBinding {
2192        use base64::Engine as _;
2193        let encode = |bytes: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes);
2194        crate::browser_provisioning::BrowserRequestBinding {
2195            version: crate::browser_provisioning::BROWSER_PROVISIONING_VERSION.to_owned(),
2196            service_name: "model".to_owned(),
2197            service_did: "did:at9p:test-service".to_owned(),
2198            service_origin: "https://model.example/".to_owned(),
2199            webtransport_url: "https://model.example/wt".to_owned(),
2200            certificate_hashes: vec![encode(&[0x44; 32])],
2201            capability: "hyprstream-rpc/1".to_owned(),
2202            scope: "model".to_owned(),
2203            carrier_profile:
2204                crate::browser_provisioning::BrowserCarrierProfile::OwnedHybridWebTransport,
2205            response_key_id: "did:at9p:test-service#response".to_owned(),
2206            response_key_digest: encode(&[0x11; 32]),
2207            request_kem_key_id: "did:at9p:test-service#mesh-kem".to_owned(),
2208            request_kem_digest: encode(&[0x22; 32]),
2209            accepted_state_digest: encode(&[0x33; 64]),
2210            accepted_state_epoch: 9,
2211            expires_at_unix_ms: i64::MAX,
2212        }
2213    }
2214
2215    fn browser_capnp_request(method_discriminator: u16) -> Vec<u8> {
2216        let mut request = Vec::with_capacity(32);
2217        request.extend_from_slice(&0u32.to_le_bytes());
2218        request.extend_from_slice(&3u32.to_le_bytes());
2219        request.extend_from_slice(&(2u64 << 32).to_le_bytes());
2220        request.extend_from_slice(&91u64.to_le_bytes());
2221        request.extend_from_slice(&(method_discriminator as u64).to_le_bytes());
2222        request
2223    }
2224
2225    #[tokio::test]
2226    async fn legacy_exports_remain_additive_on_provisioned_clients() {
2227        let binding = browser_test_binding();
2228        let (client, state, _drops) = lifecycle_client_with_browser_binding(Some(binding));
2229        let application = browser_capnp_request(7);
2230
2231        let unary = client
2232            .call(application.clone())
2233            .await
2234            .expect("legacy unary export reaches transport");
2235        let optioned = client
2236            .call_with_options(
2237                application.clone(),
2238                CallOptions::new().jwt("test-jwt".to_owned()),
2239            )
2240            .await
2241            .expect("legacy options export reaches transport");
2242        let streaming = client
2243            .call_streaming(application.clone(), [0x55; 32])
2244            .await
2245            .expect("legacy streaming export reaches transport");
2246
2247        for (request_id, framed) in [(1, unary), (2, optioned), (3, streaming)] {
2248            let (transcript, recovered) = crate::browser_provisioning::recover_request_payload(
2249                &framed,
2250                crate::browser_provisioning::BrowserTranscriptPolicy::Required {
2251                    request_id,
2252                    service_name: "model",
2253                    carrier_profile:
2254                        crate::browser_provisioning::BrowserCarrierProfile::OwnedHybridWebTransport,
2255                },
2256            )
2257            .expect("legacy export returned a sealed browser transcript");
2258            assert_eq!(
2259                transcript.expect("browser transcript").method_discriminator,
2260                7
2261            );
2262            assert_eq!(recovered, application);
2263        }
2264        assert_eq!(state.recipients.lock().len(), 3);
2265    }
2266
2267    #[tokio::test]
2268    async fn provisioned_generated_exports_reach_transport_after_bound_sealing() {
2269        let binding = browser_test_binding();
2270        let (client, state, _drops) = lifecycle_client_with_browser_binding(Some(binding));
2271        let application = browser_capnp_request(7);
2272
2273        let unary = client
2274            .call_for_service_with_method("model", 7, application.clone())
2275            .await
2276            .expect("bound generated unary reaches transport");
2277        let optioned = client
2278            .call_with_options_for_service_with_method(
2279                "model",
2280                7,
2281                application.clone(),
2282                CallOptions::new().jwt("test-jwt".to_owned()),
2283            )
2284            .await
2285            .expect("bound generated options call reaches transport");
2286        let streaming = client
2287            .call_streaming_for_service_with_method("model", 7, application.clone(), [0x55; 32])
2288            .await
2289            .expect("bound generated streaming call reaches transport");
2290
2291        for (request_id, framed) in [(1, unary), (2, optioned), (3, streaming)] {
2292            let (transcript, recovered) = crate::browser_provisioning::recover_request_payload(
2293                &framed,
2294                crate::browser_provisioning::BrowserTranscriptPolicy::Required {
2295                    request_id,
2296                    service_name: "model",
2297                    carrier_profile:
2298                        crate::browser_provisioning::BrowserCarrierProfile::OwnedHybridWebTransport,
2299                },
2300            )
2301            .expect("transport returned sealed browser transcript");
2302            assert_eq!(
2303                transcript.expect("browser transcript").method_discriminator,
2304                7
2305            );
2306            assert_eq!(recovered, application);
2307        }
2308        assert_eq!(
2309            state.recipients.lock().len(),
2310            3,
2311            "all bound calls reached transport"
2312        );
2313    }
2314
2315    #[tokio::test]
2316    async fn hostile_cleartext_response_is_rejected_before_payload_use() {
2317        let (server_sk, server_vk) = generate_signing_keypair();
2318        let (client_sk, _) = generate_signing_keypair();
2319        let server_pq_sk = crate::node_identity::derive_mesh_mldsa_key(&server_sk);
2320        let clear = crate::envelope::ResponseEnvelope::new_signed_hybrid(
2321            1,
2322            b"cleartext-response-sentinel".to_vec(),
2323            &server_sk,
2324            &server_pq_sk,
2325        );
2326
2327        let mut kem_store = KeyedKemTrustStore::new();
2328        kem_store.bind(
2329            server_vk.to_bytes(),
2330            derive_mesh_kem_recipient(&server_sk).unwrap().public(),
2331        );
2332        let server_pq_vk = crate::crypto::pq::ml_dsa_vk_from_bytes(
2333            &crate::crypto::pq::ml_dsa_sk_to_vk_bytes(&server_pq_sk),
2334        )
2335        .unwrap();
2336        let mut pq_store = crate::envelope::KeyedPqTrustStore::new();
2337        pq_store.bind(server_vk.to_bytes(), &server_pq_vk);
2338
2339        let rpc = RpcClientImpl::new(
2340            LocalSigner::new(client_sk),
2341            CleartextResponseMock(response_wire(&clear)),
2342            Some(server_vk),
2343        )
2344        .with_request_kem_store(Arc::new(kem_store))
2345        .with_response_pq_store(Arc::new(pq_store));
2346
2347        let err = rpc
2348            .call_for_service("test-service", b"request".to_vec())
2349            .await
2350            .unwrap_err();
2351        assert!(
2352            err.to_string()
2353                .contains("cleartext response rejected before payload use"),
2354            "unexpected error: {err}"
2355        );
2356    }
2357
2358    /// Full-`call()` sentinel (ported from #1032): a forbidding carrier with no
2359    /// KEM store must be refused BEFORE any byte reaches `Transport::send()`.
2360    /// This proves the guard is on the real send path, not merely on the
2361    /// `sign_envelope` helper in isolation.
2362    #[tokio::test]
2363    async fn call_over_forbidding_carrier_without_kem_store_refused_before_send() {
2364        let (_server_sk, server_vk) = generate_signing_keypair();
2365        let (client_sk, _client_vk) = generate_signing_keypair();
2366        let sent = Arc::new(AtomicBool::new(false));
2367        let rpc = RpcClientImpl::new(
2368            LocalSigner::new(client_sk),
2369            SentinelTransport {
2370                sent: sent.clone(),
2371                forbids: true,
2372            },
2373            Some(server_vk),
2374        );
2375
2376        let result = rpc.call(b"payload".to_vec()).await;
2377        assert!(
2378            result.is_err(),
2379            "forbidding carrier + no KEM store must be refused"
2380        );
2381        assert!(
2382            !sent.load(Ordering::SeqCst),
2383            "refusal MUST happen before any byte reaches the transport"
2384        );
2385    }
2386
2387    /// The mirror: a trusted carrier (forbids == false) is NOT blocked — the
2388    /// same store-less cleartext send proceeds to the transport. Proves the ban
2389    /// is not over-broadened onto trusted inproc/UDS paths. (Response unwrap
2390    /// fails on the bogus empty reply, but that is AFTER `send`.)
2391    #[tokio::test]
2392    async fn call_over_trusted_carrier_reaches_send() {
2393        let (_server_sk, server_vk) = generate_signing_keypair();
2394        let (client_sk, _client_vk) = generate_signing_keypair();
2395        let sent = Arc::new(AtomicBool::new(false));
2396        let rpc = RpcClientImpl::new(
2397            LocalSigner::new(client_sk),
2398            SentinelTransport {
2399                sent: sent.clone(),
2400                forbids: false,
2401            },
2402            Some(server_vk),
2403        );
2404
2405        let _ = rpc.call(b"payload".to_vec()).await;
2406        assert!(
2407            sent.load(Ordering::SeqCst),
2408            "trusted-carrier cleartext must NOT be blocked — send must be reached"
2409        );
2410    }
2411
2412    #[tokio::test]
2413    async fn concurrent_calls_use_distinct_recipients_and_swapped_live_responses_fail() {
2414        let (client, state, _drops) = lifecycle_client();
2415        let control = client
2416            .call_for_service("service-a", b"control".to_vec())
2417            .await
2418            .expect("unmutated control must succeed before response swapping");
2419        assert_eq!(control, b"control");
2420
2421        state.behavior.store(LIFECYCLE_SWAP, Ordering::SeqCst);
2422        let first = {
2423            let client = Arc::clone(&client);
2424            tokio::spawn(async move {
2425                client
2426                    .call_for_service("service-a", b"first".to_vec())
2427                    .await
2428            })
2429        };
2430        let second = {
2431            let client = Arc::clone(&client);
2432            tokio::spawn(async move {
2433                client
2434                    .call_for_service("service-a", b"second".to_vec())
2435                    .await
2436            })
2437        };
2438        assert!(
2439            first.await.unwrap().is_err(),
2440            "first swapped response must fail"
2441        );
2442        assert!(
2443            second.await.unwrap().is_err(),
2444            "second swapped response must fail"
2445        );
2446
2447        let recipients = state.recipients.lock();
2448        assert_eq!(recipients.len(), 3);
2449        assert_ne!(
2450            recipients[1], recipients[2],
2451            "concurrent calls must carry distinct response recipients"
2452        );
2453    }
2454
2455    #[tokio::test]
2456    async fn cancellation_drops_one_shot_response_state() {
2457        let (client, state, drops) = lifecycle_client();
2458        client
2459            .call_for_service("service-a", b"control".to_vec())
2460            .await
2461            .expect("unmutated control must succeed before cancellation");
2462        assert_eq!(drops.load(Ordering::SeqCst), 1);
2463
2464        state.behavior.store(LIFECYCLE_BLOCK, Ordering::SeqCst);
2465        let entered = state.entered.notified();
2466        let call = {
2467            let client = Arc::clone(&client);
2468            tokio::spawn(async move {
2469                client
2470                    .call_for_service("service-a", b"cancelled".to_vec())
2471                    .await
2472            })
2473        };
2474        entered.await;
2475        call.abort();
2476        assert!(call.await.unwrap_err().is_cancelled());
2477        assert_eq!(
2478            drops.load(Ordering::SeqCst),
2479            2,
2480            "cancelling a live send must drop its response secret"
2481        );
2482    }
2483
2484    #[tokio::test]
2485    async fn send_failure_drops_state_and_caller_retry_uses_fresh_recipient() {
2486        let (client, state, drops) = lifecycle_client();
2487        client
2488            .call_for_service("service-a", b"control".to_vec())
2489            .await
2490            .expect("unmutated control must succeed before send failure");
2491
2492        state.behavior.store(LIFECYCLE_FAIL_SEND, Ordering::SeqCst);
2493        assert!(client
2494            .call_for_service("service-a", b"retry-me".to_vec())
2495            .await
2496            .is_err());
2497        assert_eq!(drops.load(Ordering::SeqCst), 2);
2498
2499        state.behavior.store(LIFECYCLE_SUCCESS, Ordering::SeqCst);
2500        let retried = client
2501            .call_for_service("service-a", b"retry-me".to_vec())
2502            .await
2503            .expect("caller retry control succeeds");
2504        assert_eq!(retried, b"retry-me");
2505        assert_eq!(drops.load(Ordering::SeqCst), 3);
2506
2507        let recipients = state.recipients.lock();
2508        assert_eq!(recipients.len(), 3);
2509        assert_ne!(
2510            recipients[1], recipients[2],
2511            "caller retry must generate a fresh response recipient"
2512        );
2513    }
2514}