Skip to main content

hyprstream_rpc/
browser_provisioning.rs

1//! Accepted-current browser/WebTransport recipient provisioning.
2//!
3//! The wire document in this module is public discovery material, not an
4//! authority token. Production documents are projected by Discovery only from
5//! its opaque checkpoint-bound `ResolvedService`. Browser consumers validate
6//! the complete context and build per-resolution stores from the result; they
7//! never install the material in a process-global trust store.
8
9use std::sync::Arc;
10
11use anyhow::{Context, Result};
12use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
13use serde::{Deserialize, Serialize};
14
15use crate::crypto::hybrid_kem::{KemTrustStore, KeyedKemTrustStore, RecipientPublic, SuiteId};
16use crate::crypto::VerifyingKey;
17use crate::envelope::{KeyedPqTrustStore, PqTrustStore};
18
19pub const BROWSER_PROVISIONING_VERSION: &str = "hyprstream.browser-provisioning.v1";
20/// WebTransport CONNECT path whose accept boundary requires browser provisioning.
21pub const BROWSER_RPC_PATH: &str = "/hyprstream/browser-rpc";
22pub const MAX_PROVISIONING_BYTES: usize = 32 * 1024;
23pub const MAX_PROVISIONING_LIFETIME_MS: i64 = 60_000;
24pub const MAX_BROWSER_BINDING_BYTES: usize = 4096;
25pub const MAX_BROWSER_EXTENSION_BYTES: usize = 8 * 1024;
26pub const MAX_BROWSER_APPLICATION_BYTES: usize = 4 * 1024 * 1024;
27const MAX_BROWSER_CERTIFICATE_HASHES: usize = 16;
28const BROWSER_BOUND_PAYLOAD_MAGIC: &[u8; 16] = b"HYPR-BROWSER-V1\0";
29const BROWSER_EXTENSION_DOMAIN: &str = "hyprstream.browser-bound-request.v1";
30const BROWSER_REQUEST_DOMAIN: &[u8] = b"hyprstream.browser-request-digest.v1\0";
31const PROJECTION_SCHEMA_ID: u64 = 0x6879_7072_6270_7631;
32const PROJECTION_TYPE_ID: u64 = 0x6272_6f77_7365_7231;
33
34/// Carrier policy selected before any browser dial.
35#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
36#[serde(rename_all = "kebab-case")]
37pub enum BrowserCarrierProfile {
38    /// A Hyprstream-owned endpoint. Transport PQ is required independently of
39    /// the mandatory application HyKEM envelope.
40    /// Accept the previously emitted query spelling during the browser WASM
41    /// rollout; serialization and new queries use the canonical Serde form.
42    #[serde(alias = "owned-hybrid-webtransport")]
43    OwnedHybridWebTransport,
44    /// A stock public relay. Its WebTransport hop is explicitly classical and
45    /// untrusted; only opaque encrypted Objects may traverse it.
46    StandardPublicRelay,
47}
48
49impl BrowserCarrierProfile {
50    pub fn as_str(self) -> &'static str {
51        match self {
52            Self::OwnedHybridWebTransport => "owned-hybrid-web-transport",
53            Self::StandardPublicRelay => "standard-public-relay",
54        }
55    }
56}
57
58/// Route role bound into the provisioning context.
59#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
60#[serde(rename_all = "kebab-case")]
61pub enum BrowserRouteRole {
62    Origin,
63    Relay,
64}
65
66/// Honest transport-security classification. This is kept separate from the
67/// application HyKEM requirement so a classical relay cannot raise assurance.
68#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
69#[serde(rename_all = "kebab-case")]
70pub enum BrowserTransportSecurity {
71    OwnedHybridRequired,
72    ClassicalUntrusted,
73}
74
75/// Exact context requested by a browser consumer.
76#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
77#[serde(deny_unknown_fields)]
78pub struct BrowserProvisioningRequest {
79    pub service_name: String,
80    pub capability: String,
81    pub scope: String,
82    pub carrier_profile: BrowserCarrierProfile,
83}
84
85impl BrowserProvisioningRequest {
86    pub fn new(
87        service_name: impl Into<String>,
88        capability: impl Into<String>,
89        scope: impl Into<String>,
90        carrier_profile: BrowserCarrierProfile,
91    ) -> Result<Self> {
92        let request = Self {
93            service_name: service_name.into(),
94            capability: capability.into(),
95            scope: scope.into(),
96            carrier_profile,
97        };
98        request.validate()?;
99        Ok(request)
100    }
101
102    pub fn validate(&self) -> Result<()> {
103        validate_service_name(&self.service_name)?;
104        validate_bounded_token(&self.capability, "capability", 128)?;
105        validate_bounded_token(&self.scope, "scope", 512)?;
106        if self.carrier_profile == BrowserCarrierProfile::StandardPublicRelay {
107            anyhow::ensure!(
108                !self.scope.contains('*') && !self.scope.ends_with('/'),
109                "standard-public-relay requires an exact encrypted Object scope"
110            );
111        }
112        Ok(())
113    }
114}
115
116/// JSON document returned by the production provisioning endpoint.
117///
118/// Byte strings use canonical unpadded base64url. Deserialization rejects
119/// duplicate and unknown fields through Serde's struct visitor.
120#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
121#[serde(deny_unknown_fields)]
122pub struct BrowserProvisioningDocument {
123    pub version: String,
124    pub service_name: String,
125    pub service_did: String,
126    pub service_origin: String,
127    pub webtransport_url: String,
128    pub capability: String,
129    pub scope: String,
130    pub carrier_profile: BrowserCarrierProfile,
131    pub route_role: BrowserRouteRole,
132    pub transport_security: BrowserTransportSecurity,
133    pub response_key_id: String,
134    pub response_ed25519: String,
135    pub response_ml_dsa65: String,
136    pub request_kem_key_id: String,
137    pub request_kem_recipient: String,
138    pub accepted_state_digest: String,
139    pub accepted_state_epoch: u64,
140    pub expires_at_unix_ms: i64,
141    pub certificate_hashes: Vec<String>,
142    pub application_hybrid_required: bool,
143    pub encrypted_objects_required: bool,
144    pub projection_signer_ed25519: String,
145    pub projection_signer_ml_dsa65: String,
146    pub projection_signature: String,
147}
148
149/// Raw public values used by the trusted server-side projection.
150pub struct BrowserProvisioningMaterial {
151    pub service_name: String,
152    pub service_did: String,
153    pub service_origin: String,
154    pub webtransport_url: String,
155    pub capability: String,
156    pub scope: String,
157    pub carrier_profile: BrowserCarrierProfile,
158    pub route_role: BrowserRouteRole,
159    pub transport_security: BrowserTransportSecurity,
160    pub response_key_id: String,
161    pub response_ed25519: [u8; 32],
162    pub response_ml_dsa65: Vec<u8>,
163    pub request_kem_key_id: String,
164    pub request_kem_recipient: RecipientPublic,
165    pub accepted_state_digest: [u8; 64],
166    pub accepted_state_epoch: u64,
167    pub expires_at_unix_ms: i64,
168    pub certificate_hashes: Vec<[u8; 32]>,
169    pub encrypted_objects_required: bool,
170}
171
172impl BrowserProvisioningDocument {
173    pub fn from_material(material: BrowserProvisioningMaterial) -> Self {
174        Self {
175            version: BROWSER_PROVISIONING_VERSION.to_owned(),
176            service_name: material.service_name,
177            service_did: material.service_did,
178            service_origin: material.service_origin,
179            webtransport_url: material.webtransport_url,
180            capability: material.capability,
181            scope: material.scope,
182            carrier_profile: material.carrier_profile,
183            route_role: material.route_role,
184            transport_security: material.transport_security,
185            response_key_id: material.response_key_id,
186            response_ed25519: URL_SAFE_NO_PAD.encode(material.response_ed25519),
187            response_ml_dsa65: URL_SAFE_NO_PAD.encode(material.response_ml_dsa65),
188            request_kem_key_id: material.request_kem_key_id,
189            request_kem_recipient: URL_SAFE_NO_PAD.encode(material.request_kem_recipient.encode()),
190            accepted_state_digest: URL_SAFE_NO_PAD.encode(material.accepted_state_digest),
191            accepted_state_epoch: material.accepted_state_epoch,
192            expires_at_unix_ms: material.expires_at_unix_ms,
193            certificate_hashes: {
194                let mut hashes = material.certificate_hashes;
195                hashes.sort();
196                hashes.dedup();
197                hashes
198                    .into_iter()
199                    .map(|hash| URL_SAFE_NO_PAD.encode(hash))
200                    .collect()
201            },
202            application_hybrid_required: true,
203            encrypted_objects_required: material.encrypted_objects_required,
204            projection_signer_ed25519: String::new(),
205            projection_signer_ml_dsa65: String::new(),
206            projection_signature: String::new(),
207        }
208    }
209
210    /// Hybrid-sign the complete projection. This signature protects the HTTP
211    /// representation and cache boundary; it is not accepted-state authority.
212    pub fn sign_projection(mut self, signing_key: &crate::crypto::SigningKey) -> Result<Self> {
213        self = self.sign_projection_for_https_origin(signing_key)?;
214        anyhow::ensure!(
215            self.projection_signer_ed25519 == self.response_ed25519
216                && self.projection_signer_ml_dsa65 == self.response_ml_dsa65,
217            "projection signer is not the accepted-current response signing authority"
218        );
219        Ok(self)
220    }
221
222    /// Sign a projection served only by an authenticated HTTPS origin. The
223    /// origin's signing key need not be the target Registry/Model response key;
224    /// accepted-current service keys are independently carried in the document.
225    /// Consumers may accept this form only after the same-origin Web-PKI fetch.
226    pub fn sign_projection_for_https_origin(
227        mut self,
228        signing_key: &crate::crypto::SigningKey,
229    ) -> Result<Self> {
230        let pq_signing_key = crate::node_identity::derive_mesh_mldsa_key(signing_key);
231        let pq_verifying_key = ml_dsa::Keypair::verifying_key(&pq_signing_key);
232        let projection_ed = URL_SAFE_NO_PAD.encode(signing_key.verifying_key().to_bytes());
233        let projection_pq =
234            URL_SAFE_NO_PAD.encode(crate::crypto::pq::ml_dsa_vk_bytes(&pq_verifying_key));
235        self.projection_signer_ed25519 = projection_ed;
236        self.projection_signer_ml_dsa65 = projection_pq;
237        self.projection_signature.clear();
238        let payload = self.projection_payload()?;
239        let aad = projection_external_aad();
240        let signature = crate::crypto::cose_sign::sign_composite(
241            signing_key,
242            Some(&pq_signing_key),
243            &payload,
244            &aad,
245        )?;
246        self.projection_signature = URL_SAFE_NO_PAD.encode(signature);
247        Ok(self)
248    }
249
250    fn projection_payload(&self) -> Result<Vec<u8>> {
251        let mut unsigned = self.clone();
252        unsigned.projection_signature.clear();
253        serde_json::to_vec(&unsigned)
254            .context("failed to encode browser projection signature payload")
255    }
256}
257
258/// Accepted-state evidence copied into the signed and HyKEM-sealed request.
259/// Dispatch verifies it against the live checkpoint source before handler work.
260#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
261#[serde(deny_unknown_fields)]
262pub struct BrowserRequestBinding {
263    pub version: String,
264    pub service_name: String,
265    pub service_did: String,
266    pub service_origin: String,
267    pub webtransport_url: String,
268    pub certificate_hashes: Vec<String>,
269    pub capability: String,
270    pub scope: String,
271    pub carrier_profile: BrowserCarrierProfile,
272    pub response_key_id: String,
273    pub response_key_digest: String,
274    pub request_kem_key_id: String,
275    pub request_kem_digest: String,
276    pub accepted_state_digest: String,
277    pub accepted_state_epoch: u64,
278    pub expires_at_unix_ms: i64,
279}
280
281impl BrowserRequestBinding {
282    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
283        anyhow::ensure!(
284            bytes.len() <= MAX_BROWSER_BINDING_BYTES,
285            "browser request binding exceeds {MAX_BROWSER_BINDING_BYTES} bytes"
286        );
287        let binding: Self =
288            serde_json::from_slice(bytes).context("invalid browser request binding")?;
289        binding.validate_shape()?;
290        Ok(binding)
291    }
292
293    pub fn to_bytes(&self) -> Result<Vec<u8>> {
294        self.validate_shape()?;
295        let bytes = serde_json::to_vec(self).context("failed to encode browser request binding")?;
296        anyhow::ensure!(
297            bytes.len() <= MAX_BROWSER_BINDING_BYTES,
298            "browser request binding exceeds {MAX_BROWSER_BINDING_BYTES} bytes"
299        );
300        Ok(bytes)
301    }
302
303    pub fn validate_shape(&self) -> Result<()> {
304        anyhow::ensure!(
305            self.version == BROWSER_PROVISIONING_VERSION,
306            "invalid browser binding version"
307        );
308        validate_service_name(&self.service_name)?;
309        anyhow::ensure!(
310            self.service_did.starts_with("did:at9p:"),
311            "browser binding requires did:at9p"
312        );
313        let service_origin =
314            parse_https_url(&self.service_origin, "browser binding service origin")?;
315        let webtransport_url =
316            parse_https_url(&self.webtransport_url, "browser binding WebTransport route")?;
317        anyhow::ensure!(
318            self.service_origin == service_origin.as_str()
319                && self.webtransport_url == webtransport_url.as_str(),
320            "browser binding route evidence is not normalized"
321        );
322        anyhow::ensure!(
323            self.certificate_hashes.len() <= MAX_BROWSER_CERTIFICATE_HASHES,
324            "browser binding has too many certificate hashes"
325        );
326        let mut normalized_hashes = self.certificate_hashes.clone();
327        for hash in &normalized_hashes {
328            decode_exact::<32>(hash, "certificate hash")?;
329        }
330        normalized_hashes.sort();
331        normalized_hashes.dedup();
332        anyhow::ensure!(
333            normalized_hashes == self.certificate_hashes,
334            "browser binding certificate hashes are not normalized"
335        );
336        validate_bounded_token(&self.capability, "browser binding capability", 128)?;
337        validate_bounded_token(&self.scope, "browser binding scope", 512)?;
338        validate_key_id(&self.response_key_id, &self.service_did, "response")?;
339        validate_key_id(&self.request_kem_key_id, &self.service_did, "request KEM")?;
340        decode_exact::<32>(&self.response_key_digest, "response key digest")?;
341        decode_exact::<32>(&self.request_kem_digest, "request KEM digest")?;
342        decode_exact::<64>(&self.accepted_state_digest, "accepted-state digest")?;
343        anyhow::ensure!(
344            self.accepted_state_epoch > 0,
345            "browser binding epoch must be non-zero"
346        );
347        Ok(())
348    }
349
350    pub fn accepted_state_digest_bytes(&self) -> Result<[u8; 64]> {
351        decode_exact(&self.accepted_state_digest, "accepted-state digest")
352    }
353
354    pub fn response_key_digest_bytes(&self) -> Result<[u8; 32]> {
355        decode_exact(&self.response_key_digest, "response key digest")
356    }
357
358    pub fn request_kem_digest_bytes(&self) -> Result<[u8; 32]> {
359        decode_exact(&self.request_kem_digest, "request KEM digest")
360    }
361
362    pub fn matches_response_key(&self, key: &[u8]) -> Result<bool> {
363        use sha2::{Digest as _, Sha256};
364        Ok(self.response_key_digest_bytes()?.as_slice() == Sha256::digest(key).as_slice())
365    }
366
367    pub fn matches_request_kem(&self, recipient: &[u8]) -> Result<bool> {
368        use sha2::{Digest as _, Sha256};
369        Ok(self.request_kem_digest_bytes()?.as_slice() == Sha256::digest(recipient).as_slice())
370    }
371}
372
373#[derive(Debug, Deserialize, Serialize)]
374#[serde(deny_unknown_fields)]
375struct BrowserBoundRequestExtension {
376    version: String,
377    domain: String,
378    request_id: u64,
379    service_name: String,
380    method_discriminator: u16,
381    request_digest: String,
382    application_len: u32,
383    carrier_profile: BrowserCarrierProfile,
384    binding: BrowserRequestBinding,
385}
386
387/// Explicit dispatch profile for the inner extension. A browser extension is
388/// mandatory only on its browser carrier and is rejected as a misclassified
389/// payload on every other carrier.
390pub enum BrowserTranscriptPolicy<'a> {
391    NotBrowserCarrier,
392    Required {
393        request_id: u64,
394        service_name: &'a str,
395        carrier_profile: BrowserCarrierProfile,
396    },
397}
398
399/// Place accepted-current evidence and the application request in one bounded,
400/// canonical transcript before the normal hybrid signature and request HyKEM
401/// seal are constructed.
402pub fn bind_request_payload(
403    binding: &BrowserRequestBinding,
404    request_id: u64,
405    service_name: &str,
406    method_discriminator: u16,
407    application_payload: &[u8],
408) -> Result<Vec<u8>> {
409    anyhow::ensure!(request_id != 0, "browser request id must be non-zero");
410    anyhow::ensure!(
411        !application_payload.is_empty()
412            && application_payload.len() <= MAX_BROWSER_APPLICATION_BYTES,
413        "browser application request is empty or exceeds {MAX_BROWSER_APPLICATION_BYTES} bytes"
414    );
415    validate_service_name(service_name)?;
416    anyhow::ensure!(
417        binding.service_name == service_name,
418        "browser binding crosses the request service"
419    );
420    let extension = BrowserBoundRequestExtension {
421        version: BROWSER_PROVISIONING_VERSION.to_owned(),
422        domain: BROWSER_EXTENSION_DOMAIN.to_owned(),
423        request_id,
424        service_name: service_name.to_owned(),
425        method_discriminator,
426        request_digest: request_digest(request_id, service_name, application_payload),
427        application_len: u32::try_from(application_payload.len())
428            .context("browser application length overflow")?,
429        carrier_profile: binding.carrier_profile,
430        binding: binding.clone(),
431    };
432    let extension = serde_json::to_vec(&extension).context("encode browser request extension")?;
433    anyhow::ensure!(
434        extension.len() <= MAX_BROWSER_EXTENSION_BYTES,
435        "browser request extension exceeds {MAX_BROWSER_EXTENSION_BYTES} bytes"
436    );
437    let extension_len =
438        u32::try_from(extension.len()).context("browser extension length overflow")?;
439    let mut payload = Vec::with_capacity(
440        BROWSER_BOUND_PAYLOAD_MAGIC.len() + 4 + extension.len() + application_payload.len(),
441    );
442    payload.extend_from_slice(BROWSER_BOUND_PAYLOAD_MAGIC);
443    payload.extend_from_slice(&extension_len.to_be_bytes());
444    payload.extend_from_slice(&extension);
445    payload.extend_from_slice(application_payload);
446    Ok(payload)
447}
448
449/// Recover authenticated evidence after signature verification and HyKEM open.
450/// Canonical reserialization rejects alternate encodings as well as Serde's
451/// unknown/duplicate-field rejection.
452pub fn recover_request_payload(
453    payload: &[u8],
454    policy: BrowserTranscriptPolicy<'_>,
455) -> Result<(Option<BrowserRequestTranscript>, Vec<u8>)> {
456    let (request_id, service_name, carrier_profile) = match policy {
457        BrowserTranscriptPolicy::NotBrowserCarrier => {
458            anyhow::ensure!(
459                !payload.starts_with(BROWSER_BOUND_PAYLOAD_MAGIC),
460                "browser extension arrived on a non-browser carrier"
461            );
462            return Ok((None, payload.to_vec()));
463        }
464        BrowserTranscriptPolicy::Required {
465            request_id,
466            service_name,
467            carrier_profile,
468        } => (request_id, service_name, carrier_profile),
469    };
470    let header_len = BROWSER_BOUND_PAYLOAD_MAGIC.len() + 4;
471    anyhow::ensure!(
472        payload.len() >= header_len && payload.starts_with(BROWSER_BOUND_PAYLOAD_MAGIC),
473        "WebTransport request omitted the required browser extension"
474    );
475    let length_offset = BROWSER_BOUND_PAYLOAD_MAGIC.len();
476    let extension_len_bytes: [u8; 4] = payload[length_offset..header_len]
477        .try_into()
478        .context("invalid browser extension length prefix")?;
479    let extension_len = u32::from_be_bytes(extension_len_bytes) as usize;
480    anyhow::ensure!(
481        extension_len > 0
482            && extension_len <= MAX_BROWSER_EXTENSION_BYTES
483            && header_len + extension_len <= payload.len(),
484        "truncated or oversized browser request extension"
485    );
486    let extension_bytes = &payload[header_len..header_len + extension_len];
487    let extension: BrowserBoundRequestExtension =
488        serde_json::from_slice(extension_bytes).context("invalid browser request extension")?;
489    anyhow::ensure!(
490        serde_json::to_vec(&extension).context("canonicalize browser request extension")?
491            == extension_bytes,
492        "browser request extension is not canonical"
493    );
494    let application_start = header_len + extension_len;
495    let application_len = extension.application_len as usize;
496    anyhow::ensure!(
497        application_len > 0
498            && application_len <= MAX_BROWSER_APPLICATION_BYTES
499            && application_start
500                .checked_add(application_len)
501                .is_some_and(|total| total == payload.len()),
502        "browser application length is empty, oversized, truncated, or has trailing bytes"
503    );
504    let application_payload = &payload[application_start..];
505    anyhow::ensure!(
506        extension.version == BROWSER_PROVISIONING_VERSION
507            && extension.domain == BROWSER_EXTENSION_DOMAIN
508            && extension.request_id == request_id
509            && extension.service_name == service_name
510            && extension.carrier_profile == carrier_profile
511            && extension.binding.service_name == service_name
512            && extension.binding.carrier_profile == carrier_profile,
513        "browser request extension context mismatch"
514    );
515    extension.binding.validate_shape()?;
516    anyhow::ensure!(
517        extension.request_digest == request_digest(request_id, service_name, application_payload),
518        "browser request digest commitment mismatch"
519    );
520    Ok((
521        Some(BrowserRequestTranscript {
522            binding: extension.binding,
523            method_discriminator: extension.method_discriminator,
524        }),
525        application_payload.to_vec(),
526    ))
527}
528
529/// Authenticated browser-only transcript metadata exposed to the generated
530/// service dispatcher. The generated dispatcher independently decodes its
531/// request union and compares that schema discriminator with this commitment.
532#[derive(Clone, Debug, Eq, PartialEq)]
533pub struct BrowserRequestTranscript {
534    pub binding: BrowserRequestBinding,
535    pub method_discriminator: u16,
536}
537
538/// Independently decode the canonical top-level Cap'n Proto request-union
539/// discriminator from a fully decoded request. Generated service dispatch uses
540/// this value; the browser extension only carries the client-side commitment.
541pub fn canonical_method_discriminator(application_payload: &[u8]) -> Result<u16> {
542    let mut slice = application_payload;
543    let reader = capnp::serialize::read_message_from_flat_slice(
544        &mut slice,
545        capnp::message::ReaderOptions::default(),
546    )
547    .context("browser application is not a Cap'n Proto request")?;
548    anyhow::ensure!(slice.is_empty(), "Cap'n Proto request has trailing bytes");
549    use capnp::message::ReaderSegments as _;
550    let bytes = reader
551        .get_segments()
552        .get_segment(0)
553        .context("Cap'n Proto request omitted segment zero")?;
554    anyhow::ensure!(bytes.len() >= 24, "Cap'n Proto request root is too small");
555    let pointer = u64::from_le_bytes(bytes[..8].try_into().context("root pointer")?);
556    anyhow::ensure!(pointer & 3 == 0, "Cap'n Proto request root is not a struct");
557    let raw_offset = ((pointer >> 2) & 0x3fff_ffff) as i64;
558    let signed_offset = if raw_offset & (1 << 29) != 0 {
559        raw_offset - (1 << 30)
560    } else {
561        raw_offset
562    };
563    let data_words = ((pointer >> 32) & 0xffff) as usize;
564    let target_word = 1i64
565        .checked_add(signed_offset)
566        .filter(|target| *target >= 1)
567        .context("invalid Cap'n Proto root struct offset")? as usize;
568    anyhow::ensure!(
569        data_words >= 2 && (target_word + data_words) * 8 <= bytes.len(),
570        "Cap'n Proto request lacks the canonical top-level method discriminator"
571    );
572    let discriminator_offset = target_word * 8 + 8;
573    Ok(u16::from_le_bytes(
574        bytes[discriminator_offset..discriminator_offset + 2]
575            .try_into()
576            .context("method discriminator")?,
577    ))
578}
579
580fn request_digest(request_id: u64, service_name: &str, application_payload: &[u8]) -> String {
581    use sha2::{Digest as _, Sha256};
582    let mut digest = Sha256::new();
583    digest.update(BROWSER_REQUEST_DOMAIN);
584    digest.update(request_id.to_be_bytes());
585    digest.update((service_name.len() as u64).to_be_bytes());
586    digest.update(service_name.as_bytes());
587    digest.update((application_payload.len() as u64).to_be_bytes());
588    digest.update(application_payload);
589    URL_SAFE_NO_PAD.encode(digest.finalize())
590}
591
592#[cfg(not(target_arch = "wasm32"))]
593#[async_trait::async_trait]
594pub trait BrowserCurrentnessVerifier: Send + Sync {
595    async fn ensure_current(&self, binding: &BrowserRequestBinding) -> Result<()>;
596}
597
598/// Opaque, fully validated provisioning snapshot used for dial/seal.
599#[derive(Clone)]
600pub struct BrowserProvisioning {
601    document: BrowserProvisioningDocument,
602    server_verifying_key: VerifyingKey,
603    response_ml_dsa65: Vec<u8>,
604    request_kem_recipient: RecipientPublic,
605    accepted_state_digest: [u8; 64],
606    certificate_hashes: Vec<[u8; 32]>,
607}
608
609impl std::fmt::Debug for BrowserProvisioning {
610    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
611        formatter
612            .debug_struct("BrowserProvisioning")
613            .field("service_name", &self.document.service_name)
614            .field("service_did", &self.document.service_did)
615            .field("carrier_profile", &self.document.carrier_profile)
616            .field("accepted_state_epoch", &self.document.accepted_state_epoch)
617            .field("expires_at_unix_ms", &self.document.expires_at_unix_ms)
618            .finish_non_exhaustive()
619    }
620}
621
622impl BrowserProvisioning {
623    pub fn from_json(
624        json: &[u8],
625        expected: &BrowserProvisioningRequest,
626        now_unix_ms: i64,
627    ) -> Result<Self> {
628        Self::from_json_with_trust(json, expected, now_unix_ms, false)
629    }
630
631    fn from_json_with_trust(
632        json: &[u8],
633        expected: &BrowserProvisioningRequest,
634        now_unix_ms: i64,
635        authenticated_https_origin: bool,
636    ) -> Result<Self> {
637        anyhow::ensure!(
638            json.len() <= MAX_PROVISIONING_BYTES,
639            "browser provisioning document exceeds {MAX_PROVISIONING_BYTES} bytes"
640        );
641        let document: BrowserProvisioningDocument =
642            serde_json::from_slice(json).context("invalid browser provisioning document")?;
643        Self::validate_with_trust(document, expected, now_unix_ms, authenticated_https_origin)
644    }
645
646    pub fn validate(
647        document: BrowserProvisioningDocument,
648        expected: &BrowserProvisioningRequest,
649        now_unix_ms: i64,
650    ) -> Result<Self> {
651        Self::validate_with_trust(document, expected, now_unix_ms, false)
652    }
653
654    fn validate_with_trust(
655        document: BrowserProvisioningDocument,
656        expected: &BrowserProvisioningRequest,
657        now_unix_ms: i64,
658        authenticated_https_origin: bool,
659    ) -> Result<Self> {
660        expected.validate()?;
661        anyhow::ensure!(
662            document.version == BROWSER_PROVISIONING_VERSION,
663            "unsupported browser provisioning version"
664        );
665        if !authenticated_https_origin {
666            anyhow::ensure!(
667                document.projection_signer_ed25519 == document.response_ed25519
668                    && document.projection_signer_ml_dsa65 == document.response_ml_dsa65,
669                "projection signer is not equality-bound to accepted-current response keys"
670            );
671        }
672        let response_ed25519 = decode_exact::<32>(&document.response_ed25519, "response Ed25519")?;
673        let server_verifying_key = VerifyingKey::from_bytes(&response_ed25519)
674            .context("invalid browser response Ed25519 key")?;
675        let response_ml_dsa65 = decode(&document.response_ml_dsa65, "response ML-DSA-65")?;
676        crate::crypto::pq::ml_dsa_vk_from_bytes(&response_ml_dsa65)
677            .context("invalid browser response ML-DSA-65 key")?;
678        let projection_ed25519 = decode_exact::<32>(
679            &document.projection_signer_ed25519,
680            "projection signer Ed25519",
681        )?;
682        let projection_verifying_key = VerifyingKey::from_bytes(&projection_ed25519)
683            .context("invalid browser projection signer Ed25519 key")?;
684        let projection_pq_bytes = decode(
685            &document.projection_signer_ml_dsa65,
686            "projection signer ML-DSA-65",
687        )?;
688        let projection_pq = crate::crypto::pq::ml_dsa_vk_from_bytes(&projection_pq_bytes)
689            .context("invalid browser response ML-DSA-65 key")?;
690        let projection_signature = decode(&document.projection_signature, "projection signature")?;
691        let projection_payload = document.projection_payload()?;
692        crate::crypto::cose_sign::verify_composite(
693            &projection_signature,
694            &projection_verifying_key,
695            Some(&projection_pq),
696            &projection_payload,
697            &projection_external_aad(),
698            true,
699        )
700        .context("browser provisioning projection signature verification failed")?;
701        validate_service_name(&document.service_name)?;
702        anyhow::ensure!(
703            document.service_name == expected.service_name
704                && document.capability == expected.capability
705                && document.scope == expected.scope
706                && document.carrier_profile == expected.carrier_profile,
707            "browser provisioning context does not match the requested service/capability/scope/profile"
708        );
709        anyhow::ensure!(
710            document.service_did.starts_with("did:at9p:")
711                && !document
712                    .service_did
713                    .bytes()
714                    .any(|byte| byte.is_ascii_whitespace()),
715            "browser provisioning requires a canonical did:at9p service identity"
716        );
717        validate_key_id(&document.response_key_id, &document.service_did, "response")?;
718        validate_key_id(
719            &document.request_kem_key_id,
720            &document.service_did,
721            "request KEM",
722        )?;
723
724        let origin = parse_https_url(&document.service_origin, "service origin")?;
725        let route = parse_https_url(&document.webtransport_url, "WebTransport route")?;
726        anyhow::ensure!(
727            document.service_origin == origin.as_str()
728                && document.webtransport_url == route.as_str(),
729            "browser provisioning route evidence is not normalized"
730        );
731        match document.carrier_profile {
732            BrowserCarrierProfile::OwnedHybridWebTransport => {
733                anyhow::ensure!(
734                    document.route_role == BrowserRouteRole::Origin
735                        && document.transport_security
736                            == BrowserTransportSecurity::OwnedHybridRequired,
737                    "owned WebTransport requires the origin role and owned-hybrid transport policy"
738                );
739                anyhow::ensure!(
740                    origin.host_str() == route.host_str()
741                        && origin.port_or_known_default() == route.port_or_known_default(),
742                    "owned WebTransport route crosses the accepted service origin"
743                );
744                anyhow::ensure!(
745                    !document.encrypted_objects_required,
746                    "owned unary provisioning cannot claim the public-relay Object profile"
747                );
748            }
749            BrowserCarrierProfile::StandardPublicRelay => {
750                anyhow::ensure!(
751                    document.route_role == BrowserRouteRole::Relay
752                        && document.transport_security
753                            == BrowserTransportSecurity::ClassicalUntrusted,
754                    "public relay must remain explicitly classical/untrusted"
755                );
756                anyhow::ensure!(
757                    document.encrypted_objects_required,
758                    "public relay requires encrypted application Objects"
759                );
760            }
761        }
762        anyhow::ensure!(
763            document.application_hybrid_required,
764            "application HyKEM is mandatory for every browser carrier profile"
765        );
766        anyhow::ensure!(
767            document.accepted_state_epoch > 0,
768            "genesis-only state cannot provision a production browser recipient"
769        );
770        anyhow::ensure!(
771            document.expires_at_unix_ms > now_unix_ms,
772            "browser provisioning is expired; re-resolution required"
773        );
774        anyhow::ensure!(
775            document.expires_at_unix_ms - now_unix_ms <= MAX_PROVISIONING_LIFETIME_MS,
776            "browser provisioning lifetime exceeds the closed freshness profile"
777        );
778
779        let recipient_bytes = decode(&document.request_kem_recipient, "request KEM recipient")?;
780        let request_kem_recipient = RecipientPublic::decode(&recipient_bytes)
781            .context("invalid browser request KEM recipient")?;
782        anyhow::ensure!(
783            request_kem_recipient.suite_id == SuiteId::HyKemX25519MlKem768
784                && request_kem_recipient.eks.len()
785                    == SuiteId::HyKemX25519MlKem768.components().len(),
786            "browser request recipient is classical-only or suite-incomplete"
787        );
788        request_kem_recipient.validate()?;
789        let accepted_state_digest =
790            decode_exact::<64>(&document.accepted_state_digest, "accepted-state digest")?;
791        anyhow::ensure!(
792            document.certificate_hashes.len() <= MAX_BROWSER_CERTIFICATE_HASHES,
793            "browser provisioning has too many certificate hashes"
794        );
795        let certificate_hashes = document
796            .certificate_hashes
797            .iter()
798            .map(|value| decode_exact::<32>(value, "certificate hash"))
799            .collect::<Result<Vec<_>>>()?;
800        let mut normalized_hashes = document.certificate_hashes.clone();
801        normalized_hashes.sort();
802        normalized_hashes.dedup();
803        anyhow::ensure!(
804            normalized_hashes == document.certificate_hashes,
805            "browser provisioning certificate hashes are not normalized"
806        );
807
808        let canonical = serde_json::to_vec(&document)
809            .context("failed to canonicalize browser provisioning document")?;
810        anyhow::ensure!(
811            canonical.len() <= MAX_PROVISIONING_BYTES,
812            "browser provisioning document exceeds {MAX_PROVISIONING_BYTES} bytes"
813        );
814        Ok(Self {
815            document,
816            server_verifying_key,
817            response_ml_dsa65,
818            request_kem_recipient,
819            accepted_state_digest,
820            certificate_hashes,
821        })
822    }
823
824    pub fn ensure_fresh(&self, now_unix_ms: i64) -> Result<()> {
825        anyhow::ensure!(
826            now_unix_ms < self.document.expires_at_unix_ms,
827            "browser provisioning expired; re-resolution required"
828        );
829        Ok(())
830    }
831
832    pub fn same_snapshot(&self, other: &Self) -> bool {
833        let mut left = self.document.clone();
834        let mut right = other.document.clone();
835        // The HTTP projection TTL and its signature are freshly minted on each
836        // no-store fetch. All accepted-state, identity, route, key, capability,
837        // and signer bindings must remain byte-identical.
838        left.expires_at_unix_ms = 0;
839        right.expires_at_unix_ms = 0;
840        left.projection_signature.clear();
841        right.projection_signature.clear();
842        left == right
843    }
844
845    /// The immutable snapshot anchors identity, not an indefinitely reusable
846    /// HTTP projection. Only a newly validated, still-fresh identical projection
847    /// can supply the expiry carried by this individual request.
848    #[cfg(any(target_arch = "wasm32", test))]
849    fn refreshed_request_binding(
850        &self,
851        current: Result<Self>,
852        now_unix_ms: i64,
853    ) -> Result<BrowserRequestBinding> {
854        let current = current?;
855        current.ensure_fresh(now_unix_ms)?;
856        anyhow::ensure!(
857            self.same_snapshot(&current),
858            "accepted browser provisioning changed; re-resolution required before seal"
859        );
860        current.request_binding()
861    }
862
863    pub fn service_name(&self) -> &str {
864        &self.document.service_name
865    }
866
867    pub fn service_did(&self) -> &str {
868        &self.document.service_did
869    }
870
871    pub fn service_origin(&self) -> &str {
872        &self.document.service_origin
873    }
874
875    pub fn webtransport_url(&self) -> &str {
876        &self.document.webtransport_url
877    }
878
879    pub fn carrier_profile(&self) -> BrowserCarrierProfile {
880        self.document.carrier_profile
881    }
882
883    pub fn accepted_state_digest(&self) -> &[u8; 64] {
884        &self.accepted_state_digest
885    }
886
887    pub fn accepted_state_epoch(&self) -> u64 {
888        self.document.accepted_state_epoch
889    }
890
891    pub fn expires_at_unix_ms(&self) -> i64 {
892        self.document.expires_at_unix_ms
893    }
894
895    pub fn server_verifying_key(&self) -> VerifyingKey {
896        self.server_verifying_key
897    }
898
899    pub fn certificate_hashes(&self) -> &[[u8; 32]] {
900        &self.certificate_hashes
901    }
902
903    pub fn crypto_stores(&self) -> Result<(Arc<dyn KemTrustStore>, Arc<dyn PqTrustStore>)> {
904        let ed = self.server_verifying_key.to_bytes();
905        let mut kem = KeyedKemTrustStore::new();
906        kem.bind(ed, self.request_kem_recipient.clone());
907        let pq_key = crate::crypto::pq::ml_dsa_vk_from_bytes(&self.response_ml_dsa65)
908            .context("invalid provisioned ML-DSA-65 response key")?;
909        let mut pq = KeyedPqTrustStore::new();
910        pq.bind(ed, &pq_key);
911        Ok((Arc::new(kem), Arc::new(pq)))
912    }
913
914    pub fn request_binding(&self) -> Result<BrowserRequestBinding> {
915        use sha2::{Digest as _, Sha256};
916
917        let response_key_digest = Sha256::digest(self.server_verifying_key.to_bytes());
918        let request_kem_digest = Sha256::digest(self.request_kem_recipient.encode());
919        Ok(BrowserRequestBinding {
920            version: BROWSER_PROVISIONING_VERSION.to_owned(),
921            service_name: self.document.service_name.clone(),
922            service_did: self.document.service_did.clone(),
923            service_origin: self.document.service_origin.clone(),
924            webtransport_url: self.document.webtransport_url.clone(),
925            certificate_hashes: self.document.certificate_hashes.clone(),
926            capability: self.document.capability.clone(),
927            scope: self.document.scope.clone(),
928            carrier_profile: self.document.carrier_profile,
929            response_key_id: self.document.response_key_id.clone(),
930            response_key_digest: URL_SAFE_NO_PAD.encode(response_key_digest),
931            request_kem_key_id: self.document.request_kem_key_id.clone(),
932            request_kem_digest: URL_SAFE_NO_PAD.encode(request_kem_digest),
933            accepted_state_digest: self.document.accepted_state_digest.clone(),
934            accepted_state_epoch: self.document.accepted_state_epoch,
935            expires_at_unix_ms: self.document.expires_at_unix_ms,
936        })
937    }
938}
939
940fn projection_external_aad() -> Vec<u8> {
941    crate::crypto::cose_sign1::build_external_aad(PROJECTION_SCHEMA_ID, PROJECTION_TYPE_ID)
942}
943
944fn validate_service_name(value: &str) -> Result<()> {
945    anyhow::ensure!(!value.is_empty(), "service name is empty");
946    anyhow::ensure!(
947        value
948            .bytes()
949            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-'),
950        "service name is not canonical"
951    );
952    Ok(())
953}
954
955fn validate_bounded_token(value: &str, label: &str, max_len: usize) -> Result<()> {
956    anyhow::ensure!(
957        !value.is_empty() && value.len() <= max_len,
958        "{label} is empty or too long"
959    );
960    anyhow::ensure!(
961        !value
962            .bytes()
963            .any(|byte| byte.is_ascii_control() || byte.is_ascii_whitespace()),
964        "{label} contains whitespace or control bytes"
965    );
966    Ok(())
967}
968
969fn validate_key_id(key_id: &str, did: &str, label: &str) -> Result<()> {
970    anyhow::ensure!(
971        key_id.starts_with(&format!("{did}#")) && key_id.len() > did.len() + 1,
972        "{label} key id crosses service authority"
973    );
974    validate_bounded_token(key_id, &format!("{label} key id"), 512)
975}
976
977fn parse_https_url(value: &str, label: &str) -> Result<url::Url> {
978    let parsed = url::Url::parse(value).with_context(|| format!("invalid {label}"))?;
979    anyhow::ensure!(
980        parsed.scheme() == "https"
981            && parsed.host_str().is_some()
982            && parsed.username().is_empty()
983            && parsed.password().is_none()
984            && parsed.fragment().is_none(),
985        "{label} must be an absolute credential-free HTTPS URL"
986    );
987    Ok(parsed)
988}
989
990fn decode(value: &str, label: &str) -> Result<Vec<u8>> {
991    let decoded = URL_SAFE_NO_PAD
992        .decode(value)
993        .with_context(|| format!("invalid {label} base64url"))?;
994    anyhow::ensure!(
995        URL_SAFE_NO_PAD.encode(&decoded) == value,
996        "non-canonical {label} base64url"
997    );
998    Ok(decoded)
999}
1000
1001fn decode_exact<const N: usize>(value: &str, label: &str) -> Result<[u8; N]> {
1002    decode(value, label)?
1003        .try_into()
1004        .map_err(|_| anyhow::anyhow!("{label} must be exactly {N} bytes"))
1005}
1006
1007#[cfg(any(target_arch = "wasm32", test))]
1008fn ensure_provisioning_chunk_fits(
1009    current_len: usize,
1010    chunk_len: usize,
1011    declared_len: usize,
1012) -> Result<()> {
1013    let next_len = current_len
1014        .checked_add(chunk_len)
1015        .context("browser provisioning response length overflow")?;
1016    anyhow::ensure!(
1017        next_len <= declared_len && next_len <= MAX_PROVISIONING_BYTES,
1018        "browser provisioning response exceeded its bounded content-length"
1019    );
1020    Ok(())
1021}
1022
1023#[cfg(target_arch = "wasm32")]
1024pub async fn fetch_browser_provisioning(
1025    provisioning_origin: &str,
1026    expected: &BrowserProvisioningRequest,
1027) -> Result<BrowserProvisioning> {
1028    use wasm_bindgen::JsCast as _;
1029    use wasm_bindgen_futures::JsFuture;
1030
1031    expected.validate()?;
1032    let mut url = parse_https_url(provisioning_origin, "provisioning origin")?;
1033    anyhow::ensure!(
1034        url.path() == "/" && url.query().is_none(),
1035        "provisioning origin must not contain a path or query"
1036    );
1037    url.set_path(&format!(
1038        "/.well-known/hyprstream/browser-provisioning/{}",
1039        expected.service_name
1040    ));
1041    url.query_pairs_mut()
1042        .append_pair("capability", &expected.capability)
1043        .append_pair("scope", &expected.scope)
1044        .append_pair("carrier_profile", expected.carrier_profile.as_str());
1045    let init = web_sys::RequestInit::new();
1046    init.set_method("GET");
1047    init.set_cache(web_sys::RequestCache::NoStore);
1048    init.set_credentials(web_sys::RequestCredentials::SameOrigin);
1049    init.set_redirect(web_sys::RequestRedirect::Error);
1050    let fetch_request =
1051        web_sys::Request::new_with_str_and_init(url.as_str(), &init).map_err(|error| {
1052            anyhow::anyhow!("browser provisioning request construction failed: {error:?}")
1053        })?;
1054    let window = web_sys::window().ok_or_else(|| anyhow::anyhow!("browser window unavailable"))?;
1055    let response_value = JsFuture::from(window.fetch_with_request(&fetch_request))
1056        .await
1057        .map_err(|error| anyhow::anyhow!("browser provisioning fetch failed: {error:?}"))?;
1058    let response: web_sys::Response = response_value
1059        .dyn_into()
1060        .map_err(|_| anyhow::anyhow!("browser provisioning fetch returned a non-Response"))?;
1061    anyhow::ensure!(
1062        response.ok() && !response.redirected(),
1063        "browser provisioning endpoint returned HTTP {} or redirected",
1064        response.status()
1065    );
1066    let response_url = parse_https_url(&response.url(), "provisioning response URL")?;
1067    anyhow::ensure!(
1068        response_url.origin() == url.origin(),
1069        "browser provisioning response crossed its authenticated origin"
1070    );
1071    let headers = response.headers();
1072    let content_type = headers
1073        .get("content-type")
1074        .map_err(|error| {
1075            anyhow::anyhow!("browser provisioning content-type unavailable: {error:?}")
1076        })?
1077        .ok_or_else(|| anyhow::anyhow!("browser provisioning response omitted content-type"))?;
1078    anyhow::ensure!(
1079        content_type
1080            .split(';')
1081            .next()
1082            .is_some_and(|value| value.trim().eq_ignore_ascii_case("application/json")),
1083        "browser provisioning response is not application/json"
1084    );
1085    let cache_control = headers
1086        .get("cache-control")
1087        .map_err(|error| {
1088            anyhow::anyhow!("browser provisioning cache policy unavailable: {error:?}")
1089        })?
1090        .ok_or_else(|| anyhow::anyhow!("browser provisioning response omitted cache-control"))?;
1091    anyhow::ensure!(
1092        cache_control
1093            .split(',')
1094            .any(|directive| directive.trim().eq_ignore_ascii_case("no-store")),
1095        "browser provisioning response is cacheable"
1096    );
1097    let content_length = headers
1098        .get("content-length")
1099        .map_err(|error| {
1100            anyhow::anyhow!("browser provisioning content length unavailable: {error:?}")
1101        })?
1102        .ok_or_else(|| anyhow::anyhow!("browser provisioning response omitted content-length"))?
1103        .parse::<usize>()
1104        .context("invalid browser provisioning content-length")?;
1105    anyhow::ensure!(
1106        content_length <= MAX_PROVISIONING_BYTES,
1107        "browser provisioning response exceeds {MAX_PROVISIONING_BYTES} bytes"
1108    );
1109    let body = response
1110        .body()
1111        .ok_or_else(|| anyhow::anyhow!("browser provisioning response omitted its body"))?;
1112    let reader: web_sys::ReadableStreamDefaultReader = body.get_reader().unchecked_into();
1113    let mut bytes = Vec::with_capacity(content_length);
1114    loop {
1115        let result = JsFuture::from(reader.read()).await.map_err(|error| {
1116            anyhow::anyhow!("browser provisioning response read failed: {error:?}")
1117        })?;
1118        let done = js_sys::Reflect::get(&result, &wasm_bindgen::JsValue::from_str("done"))
1119            .map_err(|_| anyhow::anyhow!("browser provisioning response chunk omitted done"))?
1120            .as_bool()
1121            .ok_or_else(|| {
1122                anyhow::anyhow!("browser provisioning response chunk had invalid done")
1123            })?;
1124        if done {
1125            break;
1126        }
1127        let value = js_sys::Reflect::get(&result, &wasm_bindgen::JsValue::from_str("value"))
1128            .map_err(|_| anyhow::anyhow!("browser provisioning response chunk omitted value"))?;
1129        let chunk = js_sys::Uint8Array::new(&value);
1130        let chunk_len = usize::try_from(chunk.length())
1131            .context("browser provisioning response chunk length overflow")?;
1132        ensure_provisioning_chunk_fits(bytes.len(), chunk_len, content_length)?;
1133        let start = bytes.len();
1134        bytes.resize(start + chunk_len, 0);
1135        chunk.copy_to(&mut bytes[start..]);
1136    }
1137    reader.release_lock();
1138    anyhow::ensure!(
1139        bytes.len() == content_length,
1140        "browser provisioning response size did not match its bounded content-length"
1141    );
1142    let now = chrono::Utc::now().timestamp_millis();
1143    // The response URL was checked against the requested HTTPS origin above.
1144    // Only this transport-authenticated path may accept an origin signer
1145    // distinct from the target service's response key.
1146    let provisioned = BrowserProvisioning::from_json_with_trust(&bytes, expected, now, true)?;
1147    let service_origin = parse_https_url(provisioned.service_origin(), "service origin")?;
1148    anyhow::ensure!(
1149        service_origin.host_str() == url.host_str(),
1150        "browser provisioning was not fetched from the accepted service domain"
1151    );
1152    Ok(provisioned)
1153}
1154
1155/// WASM pre-seal guard which re-fetches the accepted-current document before
1156/// every request and rejects any state/key/service/profile change. The caller
1157/// must construct a new client from the new snapshot after invalidation.
1158#[cfg(target_arch = "wasm32")]
1159pub struct BrowserProvisioningGuard {
1160    provisioning_origin: String,
1161    expected: BrowserProvisioningRequest,
1162    snapshot: BrowserProvisioning,
1163}
1164
1165#[cfg(target_arch = "wasm32")]
1166impl BrowserProvisioningGuard {
1167    pub fn new(
1168        provisioning_origin: impl Into<String>,
1169        expected: BrowserProvisioningRequest,
1170        snapshot: BrowserProvisioning,
1171    ) -> Self {
1172        Self {
1173            provisioning_origin: provisioning_origin.into(),
1174            expected,
1175            snapshot,
1176        }
1177    }
1178}
1179
1180#[cfg(target_arch = "wasm32")]
1181#[async_trait::async_trait(?Send)]
1182impl crate::rpc_client::PreSealGuard for BrowserProvisioningGuard {
1183    async fn ensure_current(&self) -> Result<()> {
1184        self.current_browser_binding().await?;
1185        Ok(())
1186    }
1187
1188    async fn current_browser_binding(&self) -> Result<Option<BrowserRequestBinding>> {
1189        let current = fetch_browser_provisioning(&self.provisioning_origin, &self.expected).await;
1190        self.snapshot
1191            .refreshed_request_binding(current, chrono::Utc::now().timestamp_millis())
1192            .map(Some)
1193    }
1194}
1195
1196#[cfg(test)]
1197#[allow(clippy::expect_used)]
1198mod tests {
1199    use super::*;
1200
1201    #[test]
1202    fn browser_carrier_query_spelling_matches_wire_profile() {
1203        let profile = BrowserCarrierProfile::OwnedHybridWebTransport;
1204        assert_eq!(profile.as_str(), "owned-hybrid-web-transport");
1205        assert_eq!(
1206            serde_json::to_string(&profile).expect("serialize profile"),
1207            format!("\"{}\"", profile.as_str())
1208        );
1209        for value in ["owned-hybrid-web-transport", "owned-hybrid-webtransport"] {
1210            let parsed: BrowserCarrierProfile =
1211                serde_json::from_str(&format!("\"{value}\"")).expect("parse profile");
1212            assert_eq!(parsed, profile);
1213        }
1214        assert!(serde_json::from_str::<BrowserCarrierProfile>(
1215            "\"owned-hybrid-webtransport-untrusted\""
1216        )
1217        .is_err());
1218    }
1219
1220    fn material(now: i64) -> BrowserProvisioningMaterial {
1221        let response = crate::crypto::SigningKey::from_bytes(&[0x41; 32]);
1222        let pq = crate::node_identity::derive_mesh_mldsa_key(&response);
1223        let pq_vk = ml_dsa::Keypair::verifying_key(&pq);
1224        let recipient = crate::node_identity::derive_mesh_kem_recipient(&response)
1225            .expect("derive KEM")
1226            .public();
1227        BrowserProvisioningMaterial {
1228            service_name: "model".to_owned(),
1229            service_did: "did:at9p:test-service".to_owned(),
1230            service_origin: "https://model.example/".to_owned(),
1231            webtransport_url: "https://model.example/wt".to_owned(),
1232            capability: "hyprstream-rpc/1".to_owned(),
1233            scope: "model".to_owned(),
1234            carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1235            route_role: BrowserRouteRole::Origin,
1236            transport_security: BrowserTransportSecurity::OwnedHybridRequired,
1237            response_key_id: "did:at9p:test-service#response".to_owned(),
1238            response_ed25519: response.verifying_key().to_bytes(),
1239            response_ml_dsa65: crate::crypto::pq::ml_dsa_vk_bytes(&pq_vk),
1240            request_kem_key_id: "did:at9p:test-service#mesh-kem".to_owned(),
1241            request_kem_recipient: recipient,
1242            accepted_state_digest: [0x33; 64],
1243            accepted_state_epoch: 9,
1244            expires_at_unix_ms: now + 30_000,
1245            certificate_hashes: vec![[0x55; 32]],
1246            encrypted_objects_required: false,
1247        }
1248    }
1249
1250    fn request() -> BrowserProvisioningRequest {
1251        BrowserProvisioningRequest::new(
1252            "model",
1253            "hyprstream-rpc/1",
1254            "model",
1255            BrowserCarrierProfile::OwnedHybridWebTransport,
1256        )
1257        .expect("request")
1258    }
1259
1260    fn signed(material: BrowserProvisioningMaterial) -> BrowserProvisioningDocument {
1261        BrowserProvisioningDocument::from_material(material)
1262            .sign_projection(&crate::crypto::SigningKey::from_bytes(&[0x41; 32]))
1263            .expect("sign projection")
1264    }
1265
1266    fn application_request(method_discriminator: u16) -> Vec<u8> {
1267        // One three-word segment containing a direct root struct with two data
1268        // words: the generated service request id followed by its union tag.
1269        let mut request = Vec::with_capacity(32);
1270        request.extend_from_slice(&0u32.to_le_bytes());
1271        request.extend_from_slice(&3u32.to_le_bytes());
1272        request.extend_from_slice(&(2u64 << 32).to_le_bytes());
1273        request.extend_from_slice(&91u64.to_le_bytes());
1274        request.extend_from_slice(&(method_discriminator as u64).to_le_bytes());
1275        request
1276    }
1277
1278    #[test]
1279    fn accepted_current_hybrid_document_builds_resolution_local_stores() {
1280        let now = 1_000_000;
1281        let provisioned = BrowserProvisioning::validate(signed(material(now)), &request(), now)
1282            .expect("valid provisioning");
1283        let (kem, pq) = provisioned.crypto_stores().expect("stores");
1284        let ed = provisioned.server_verifying_key().to_bytes();
1285        assert!(kem.kem_recipient_for(&ed).is_some());
1286        assert!(pq.ml_dsa_key_for(&ed).is_some());
1287
1288        let binding = provisioned.request_binding().expect("binding");
1289        let application = application_request(7);
1290        let sealed_transcript =
1291            bind_request_payload(&binding, 17, "model", 7, &application).expect("bind payload");
1292        let (opened_binding, opened_payload) = recover_request_payload(
1293            &sealed_transcript,
1294            BrowserTranscriptPolicy::Required {
1295                request_id: 17,
1296                service_name: "model",
1297                carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1298            },
1299        )
1300        .expect("open payload");
1301        assert_eq!(opened_binding.expect("transcript").binding, binding);
1302        assert_eq!(opened_payload, application);
1303    }
1304
1305    #[test]
1306    fn distinct_https_origin_signer_requires_authenticated_fetch_boundary() {
1307        let now = 1_000_000;
1308        let origin_key = crate::crypto::SigningKey::from_bytes(&[0x42; 32]);
1309        let unsigned = BrowserProvisioningDocument::from_material(material(now));
1310        assert!(unsigned.clone().sign_projection(&origin_key).is_err());
1311        let signed = unsigned
1312            .clone()
1313            .sign_projection_for_https_origin(&origin_key)
1314            .expect("sign HTTPS projection");
1315        let json = serde_json::to_vec(&signed).expect("encode projection");
1316        assert!(BrowserProvisioning::from_json(&json, &request(), now).is_err());
1317        let provisioned = BrowserProvisioning::from_json_with_trust(&json, &request(), now, true)
1318            .expect("HTTPS-authenticated projection");
1319        assert_eq!(
1320            provisioned.server_verifying_key().to_bytes(),
1321            crate::crypto::SigningKey::from_bytes(&[0x41; 32])
1322                .verifying_key()
1323                .to_bytes()
1324        );
1325        let mut tampered = signed.clone();
1326        tampered.response_key_id.push_str("-attacker");
1327        let tampered_json = serde_json::to_vec(&tampered).expect("encode mutation");
1328        assert!(
1329            BrowserProvisioning::from_json_with_trust(&tampered_json, &request(), now, true,)
1330                .is_err()
1331        );
1332        let mut malformed_response_key = unsigned;
1333        malformed_response_key.response_ml_dsa65 = URL_SAFE_NO_PAD.encode([0u8; 4]);
1334        let malformed_response_key = malformed_response_key
1335            .sign_projection_for_https_origin(&origin_key)
1336            .expect("sign malformed response key projection");
1337        let malformed_json =
1338            serde_json::to_vec(&malformed_response_key).expect("encode malformed projection");
1339        assert!(
1340            BrowserProvisioning::from_json_with_trust(&malformed_json, &request(), now, true)
1341                .is_err()
1342        );
1343        let mut wrong_signer = signed;
1344        wrong_signer.projection_signer_ed25519 = URL_SAFE_NO_PAD.encode(
1345            crate::crypto::SigningKey::from_bytes(&[0x43; 32])
1346                .verifying_key()
1347                .to_bytes(),
1348        );
1349        let wrong_signer_json = serde_json::to_vec(&wrong_signer).expect("encode signer mutation");
1350        assert!(BrowserProvisioning::from_json_with_trust(
1351            &wrong_signer_json,
1352            &request(),
1353            now,
1354            true,
1355        )
1356        .is_err());
1357    }
1358
1359    #[test]
1360    fn stale_cross_service_and_classical_only_documents_fail_closed() {
1361        let now = 1_000_000;
1362        let mut stale = material(now);
1363        stale.expires_at_unix_ms = now;
1364        assert!(BrowserProvisioning::validate(signed(stale), &request(), now).is_err());
1365
1366        let mut crossed = material(now);
1367        crossed.service_name = "policy".to_owned();
1368        assert!(BrowserProvisioning::validate(signed(crossed), &request(), now).is_err());
1369
1370        let mut classical = BrowserProvisioningDocument::from_material(material(now));
1371        classical.request_kem_recipient = URL_SAFE_NO_PAD.encode([0x11; 32]);
1372        classical = classical
1373            .sign_projection(&crate::crypto::SigningKey::from_bytes(&[0x41; 32]))
1374            .expect("sign classical mutation");
1375        assert!(BrowserProvisioning::validate(classical, &request(), now).is_err());
1376    }
1377
1378    #[test]
1379    fn refreshed_browser_projection_keeps_expired_anchor_but_requires_fresh_identical_authority() {
1380        let then = 1_000_000;
1381        let now = then + 60_000;
1382        let anchor = BrowserProvisioning::validate(signed(material(then)), &request(), then)
1383            .expect("anchor");
1384        assert!(anchor.ensure_fresh(now).is_err()); // actual old pre-fetch failure
1385        let current =
1386            BrowserProvisioning::validate(signed(material(now)), &request(), now).expect("current");
1387        let expected = current.request_binding().expect("current binding");
1388        assert_eq!(
1389            anchor
1390                .refreshed_request_binding(Ok(current.clone()), now)
1391                .expect("fresh identical projection"),
1392            expected
1393        );
1394        assert_eq!(anchor.expires_at_unix_ms(), then + 30_000); // never mutate the anchor
1395        assert!(anchor
1396            .refreshed_request_binding(Err(anyhow::anyhow!("fixture network failure")), now)
1397            .is_err());
1398        assert!(anchor
1399            .refreshed_request_binding(Ok(current.clone()), now + 30_000)
1400            .is_err());
1401        // Exercise EVERY stable document field, not just selected key/view fields.
1402        // Fetch validation remains independently covered by the signed-document tests.
1403        let document = serde_json::to_value(&current.document).expect("document JSON");
1404        for field in document.as_object().expect("document object").keys() {
1405            if field == "expires_at_unix_ms" || field == "projection_signature" {
1406                continue;
1407            }
1408            let mut changed = current.clone();
1409            let mut value = document.clone();
1410            let slot = value.get_mut(field).expect("existing field");
1411            match slot {
1412                serde_json::Value::String(text) => text.push('x'),
1413                serde_json::Value::Number(number) => {
1414                    *number = (number.as_u64().expect("unsigned field") + 1).into();
1415                }
1416                serde_json::Value::Bool(flag) => *flag = !*flag,
1417                serde_json::Value::Array(values) => values.push(serde_json::json!("fixture")),
1418                _ => panic!("unexpected document field shape: {field}"),
1419            }
1420            // Enum mutations may fail to deserialize first: that is also fail-closed.
1421            if let Ok(changed_document) = serde_json::from_value(value) {
1422                changed.document = changed_document;
1423                assert!(
1424                    anchor.refreshed_request_binding(Ok(changed), now).is_err(),
1425                    "field {field}"
1426                );
1427            }
1428        }
1429    }
1430
1431    #[test]
1432    fn substituted_projection_signer_or_signature_fails_closed() {
1433        let now = 1_000_000;
1434        let mut substituted_key = signed(material(now));
1435        substituted_key.projection_signer_ed25519 = URL_SAFE_NO_PAD.encode(
1436            crate::crypto::SigningKey::from_bytes(&[0x72; 32])
1437                .verifying_key()
1438                .to_bytes(),
1439        );
1440        assert!(BrowserProvisioning::validate(substituted_key, &request(), now).is_err());
1441
1442        let mut substituted_pq_key = signed(material(now));
1443        substituted_pq_key.projection_signer_ml_dsa65 = URL_SAFE_NO_PAD.encode(vec![0x73; 1952]);
1444        assert!(BrowserProvisioning::validate(substituted_pq_key, &request(), now).is_err());
1445
1446        let mut substituted_signature = signed(material(now));
1447        let mut signature = decode(
1448            &substituted_signature.projection_signature,
1449            "test signature",
1450        )
1451        .expect("decode signature");
1452        let last = signature.len() - 1;
1453        signature[last] ^= 1;
1454        substituted_signature.projection_signature = URL_SAFE_NO_PAD.encode(signature);
1455        assert!(BrowserProvisioning::validate(substituted_signature, &request(), now).is_err());
1456
1457        assert!(recover_request_payload(
1458            b"unbound application request",
1459            BrowserTranscriptPolicy::Required {
1460                request_id: 17,
1461                service_name: "model",
1462                carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1463            },
1464        )
1465        .is_err());
1466    }
1467
1468    #[test]
1469    fn streaming_body_cap_rejects_lying_length_and_oversize_before_growth() {
1470        assert!(ensure_provisioning_chunk_fits(0, 9, 8).is_err());
1471        assert!(ensure_provisioning_chunk_fits(
1472            0,
1473            MAX_PROVISIONING_BYTES + 1,
1474            MAX_PROVISIONING_BYTES,
1475        )
1476        .is_err());
1477        assert!(ensure_provisioning_chunk_fits(7, 1, 8).is_ok());
1478    }
1479
1480    #[test]
1481    fn inner_extension_is_canonical_bounded_and_profile_gated() {
1482        let now = 1_000_000;
1483        let provisioned = BrowserProvisioning::validate(signed(material(now)), &request(), now)
1484            .expect("valid provisioning");
1485        let binding = provisioned.request_binding().expect("binding");
1486        let application = application_request(7);
1487        let framed = bind_request_payload(&binding, 23, "model", 7, &application).expect("frame");
1488        let required = || BrowserTranscriptPolicy::Required {
1489            request_id: 23,
1490            service_name: "model",
1491            carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1492        };
1493
1494        let (_, recovered) = recover_request_payload(&framed, required()).expect("recover");
1495        assert_eq!(recovered, application);
1496        let (none, compatible) =
1497            recover_request_payload(&application, BrowserTranscriptPolicy::NotBrowserCarrier)
1498                .expect("explicit non-browser compatibility");
1499        assert!(none.is_none());
1500        assert_eq!(compatible, application);
1501        assert!(
1502            recover_request_payload(&framed, BrowserTranscriptPolicy::NotBrowserCarrier).is_err()
1503        );
1504
1505        assert!(recover_request_payload(&framed[..framed.len() - 1], required()).is_err());
1506        let mut trailing = framed.clone();
1507        trailing.push(0);
1508        assert!(recover_request_payload(&trailing, required()).is_err());
1509        assert!(recover_request_payload(
1510            &framed,
1511            BrowserTranscriptPolicy::Required {
1512                request_id: 24,
1513                service_name: "model",
1514                carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1515            }
1516        )
1517        .is_err());
1518        assert!(recover_request_payload(
1519            &framed,
1520            BrowserTranscriptPolicy::Required {
1521                request_id: 23,
1522                service_name: "policy",
1523                carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
1524            }
1525        )
1526        .is_err());
1527        assert!(recover_request_payload(
1528            &framed,
1529            BrowserTranscriptPolicy::Required {
1530                request_id: 23,
1531                service_name: "model",
1532                carrier_profile: BrowserCarrierProfile::StandardPublicRelay,
1533            }
1534        )
1535        .is_err());
1536
1537        let header_len = BROWSER_BOUND_PAYLOAD_MAGIC.len() + 4;
1538        let extension_len = u32::from_be_bytes(
1539            framed[BROWSER_BOUND_PAYLOAD_MAGIC.len()..header_len]
1540                .try_into()
1541                .expect("length"),
1542        ) as usize;
1543        assert!(
1544            recover_request_payload(&framed[..header_len + extension_len - 1], required(),)
1545                .is_err()
1546        );
1547        let extension = &framed[header_len..header_len + extension_len];
1548        let application = &framed[header_len + extension_len..];
1549        let reframe = |replacement: &[u8], replacement_application: &[u8]| {
1550            let mut value = Vec::new();
1551            value.extend_from_slice(BROWSER_BOUND_PAYLOAD_MAGIC);
1552            value.extend_from_slice(&(replacement.len() as u32).to_be_bytes());
1553            value.extend_from_slice(replacement);
1554            value.extend_from_slice(replacement_application);
1555            value
1556        };
1557
1558        // Recovery authenticates and returns the explicit client commitment;
1559        // generated service dispatch independently decodes the request union
1560        // and rejects a cross-method commitment before invoking the handler.
1561        let mut mismatched_method: BrowserBoundRequestExtension =
1562            serde_json::from_slice(extension).expect("extension");
1563        mismatched_method.method_discriminator += 1;
1564        let mismatched_method = serde_json::to_vec(&mismatched_method).expect("method extension");
1565        let (transcript, recovered) =
1566            recover_request_payload(&reframe(&mismatched_method, application), required())
1567                .expect("recover authenticated explicit method commitment");
1568        assert_eq!(recovered, application);
1569        let transcript = transcript.expect("browser transcript");
1570        assert_eq!(transcript.method_discriminator, 8);
1571        let mut ctx = crate::service::EnvelopeContext::from_callback_service(23, "model");
1572        ctx.browser_method_discriminator = Some(transcript.method_discriminator);
1573        assert!(ctx.ensure_browser_method(7).is_err());
1574
1575        let different_method = application_request(8);
1576        assert_eq!(different_method.len(), application.len());
1577        assert!(
1578            recover_request_payload(&reframe(extension, &different_method), required()).is_err()
1579        );
1580
1581        let mut unknown_version: BrowserBoundRequestExtension =
1582            serde_json::from_slice(extension).expect("extension");
1583        unknown_version.version = "hyprstream.browser-provisioning.v2".to_owned();
1584        let unknown_version = serde_json::to_vec(&unknown_version).expect("version extension");
1585        assert!(
1586            recover_request_payload(&reframe(&unknown_version, application), required()).is_err()
1587        );
1588
1589        let mut noncanonical = vec![b' '];
1590        noncanonical.extend_from_slice(extension);
1591        assert!(recover_request_payload(&reframe(&noncanonical, application), required()).is_err());
1592
1593        let mut unknown = extension[..extension.len() - 1].to_vec();
1594        unknown.extend_from_slice(br#","unknown":true}"#);
1595        let unknown_error = recover_request_payload(&reframe(&unknown, application), required())
1596            .expect_err("unknown field must reject");
1597        assert!(format!("{unknown_error:#}").contains("unknown field"));
1598
1599        let mut duplicate = extension[..extension.len() - 1].to_vec();
1600        duplicate.extend_from_slice(br#","version":"hyprstream.browser-provisioning.v1"}"#);
1601        let duplicate_error =
1602            recover_request_payload(&reframe(&duplicate, application), required())
1603                .expect_err("duplicate field must reject");
1604        assert!(format!("{duplicate_error:#}").contains("duplicate field"));
1605
1606        let mut oversized = Vec::from(*BROWSER_BOUND_PAYLOAD_MAGIC);
1607        oversized.extend_from_slice(&((MAX_BROWSER_EXTENSION_BYTES + 1) as u32).to_be_bytes());
1608        assert!(recover_request_payload(&oversized, required()).is_err());
1609        assert!(bind_request_payload(&binding, 23, "model", 7, &[]).is_err());
1610        assert!(bind_request_payload(
1611            &binding,
1612            23,
1613            "model",
1614            7,
1615            &vec![0; MAX_BROWSER_APPLICATION_BYTES + 1]
1616        )
1617        .is_err());
1618    }
1619
1620    #[test]
1621    fn public_relay_scope_must_be_exact() {
1622        let exact = BrowserProvisioningRequest::new(
1623            "model",
1624            "hyprstream-moq/1",
1625            "tenant-a/track-a",
1626            BrowserCarrierProfile::StandardPublicRelay,
1627        );
1628        assert!(exact.is_ok());
1629        for wildcard in ["*", "tenant-a/*", "tenant-*/track-a", "tenant-a/"] {
1630            assert!(
1631                BrowserProvisioningRequest::new(
1632                    "model",
1633                    "hyprstream-moq/1",
1634                    wildcard,
1635                    BrowserCarrierProfile::StandardPublicRelay,
1636                )
1637                .is_err(),
1638                "wildcard relay scope {wildcard:?} must be rejected"
1639            );
1640        }
1641    }
1642
1643    #[test]
1644    fn public_relay_is_classical_untrusted_and_requires_encrypted_objects() {
1645        let now = 1_000_000;
1646        let mut relay = material(now);
1647        relay.capability = "hyprstream-moq/1".to_owned();
1648        relay.scope = "tenant-a/track-a".to_owned();
1649        relay.carrier_profile = BrowserCarrierProfile::StandardPublicRelay;
1650        relay.route_role = BrowserRouteRole::Relay;
1651        relay.transport_security = BrowserTransportSecurity::ClassicalUntrusted;
1652        relay.webtransport_url = "https://relay.example/moq".to_owned();
1653        relay.certificate_hashes.clear();
1654        relay.encrypted_objects_required = true;
1655        let request = BrowserProvisioningRequest::new(
1656            "model",
1657            "hyprstream-moq/1",
1658            "tenant-a/track-a",
1659            BrowserCarrierProfile::StandardPublicRelay,
1660        )
1661        .expect("request");
1662        BrowserProvisioning::validate(signed(relay), &request, now).expect("valid relay profile");
1663
1664        let mut omitted = material(now);
1665        omitted.capability = "hyprstream-moq/1".to_owned();
1666        omitted.scope = "tenant-a/track-a".to_owned();
1667        omitted.carrier_profile = BrowserCarrierProfile::StandardPublicRelay;
1668        omitted.route_role = BrowserRouteRole::Relay;
1669        omitted.transport_security = BrowserTransportSecurity::ClassicalUntrusted;
1670        omitted.webtransport_url = "https://relay.example/moq".to_owned();
1671        assert!(BrowserProvisioning::validate(signed(omitted), &request, now,).is_err());
1672    }
1673}