1use 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";
20pub 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#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
36#[serde(rename_all = "kebab-case")]
37pub enum BrowserCarrierProfile {
38 #[serde(alias = "owned-hybrid-webtransport")]
43 OwnedHybridWebTransport,
44 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#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
60#[serde(rename_all = "kebab-case")]
61pub enum BrowserRouteRole {
62 Origin,
63 Relay,
64}
65
66#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
69#[serde(rename_all = "kebab-case")]
70pub enum BrowserTransportSecurity {
71 OwnedHybridRequired,
72 ClassicalUntrusted,
73}
74
75#[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#[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
149pub 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 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 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#[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
387pub enum BrowserTranscriptPolicy<'a> {
391 NotBrowserCarrier,
392 Required {
393 request_id: u64,
394 service_name: &'a str,
395 carrier_profile: BrowserCarrierProfile,
396 },
397}
398
399pub 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
449pub 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#[derive(Clone, Debug, Eq, PartialEq)]
533pub struct BrowserRequestTranscript {
534 pub binding: BrowserRequestBinding,
535 pub method_discriminator: u16,
536}
537
538pub 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#[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 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 #[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(¤t),
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 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#[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 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()); 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); 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 let document = serde_json::to_value(¤t.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 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 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}