Skip to main content

hyprstream_core/server/routes/
browser_provisioning.rs

1//! Browser/WebTransport accepted-current provisioning boundary.
2
3use axum::extract::{Path, Query, State};
4use axum::http::{header, HeaderValue, StatusCode};
5use axum::response::{IntoResponse, Response};
6use hyprstream_rpc::browser_provisioning::{BrowserCarrierProfile, BrowserProvisioningRequest};
7use serde::{Deserialize, Serialize};
8use std::sync::Arc;
9
10#[derive(Deserialize)]
11#[serde(deny_unknown_fields)]
12pub struct BrowserProvisioningQuery {
13    capability: String,
14    scope: String,
15    carrier_profile: BrowserCarrierProfile,
16}
17
18/// Return a no-store public-key projection minted only by Discovery's
19/// checkpoint-backed production resolver. The route is public because it
20/// carries no credential or private material; authenticity comes from the
21/// accepted-current resolver and the browser's authenticated HTTPS fetch.
22pub async fn browser_provisioning(
23    State(state): State<crate::server::state::ServerState>,
24    Path(service): Path<String>,
25    Query(query): Query<BrowserProvisioningQuery>,
26) -> Response {
27    serve_browser_provisioning(service, query, &state.signing_key, false).await
28}
29
30/// The public HTTPS listener belongs to OAuth, not the OAI HTTP
31/// listener. Its Web-PKI identity authenticates this projection; the target
32/// service's response/KEM keys still come only from accepted-current state.
33pub async fn oauth_browser_provisioning(
34    State(state): State<Arc<crate::services::oauth::state::OAuthState>>,
35    Path(service): Path<String>,
36    Query(query): Query<BrowserProvisioningQuery>,
37) -> Response {
38    if service != "registry" && service != "model" {
39        return StatusCode::NOT_FOUND.into_response();
40    }
41    let Some(signing_key) = state.browser_provisioning_signer.as_ref() else {
42        return StatusCode::SERVICE_UNAVAILABLE.into_response();
43    };
44    serve_browser_provisioning(service, query, signing_key, true).await
45}
46
47async fn serve_browser_provisioning(
48    service: String,
49    query: BrowserProvisioningQuery,
50    signing_key: &hyprstream_rpc::crypto::SigningKey,
51    authenticated_https_origin: bool,
52) -> Response {
53    let request = match BrowserProvisioningRequest::new(
54        service,
55        query.capability,
56        query.scope,
57        query.carrier_profile,
58    ) {
59        Ok(request) => request,
60        Err(error) => {
61            return bounded_json_response(
62                StatusCode::BAD_REQUEST,
63                &serde_json::json!({ "error": error.to_string() }),
64            );
65        }
66    };
67    let document = match hyprstream_discovery::production_browser_provisioning(request).await {
68        Ok(document) => match if authenticated_https_origin {
69            document.sign_projection_for_https_origin(signing_key)
70        } else {
71            document.sign_projection(signing_key)
72        } {
73            Ok(document) => document,
74            Err(error) => {
75                tracing::error!(error = %error, "browser projection signing failed closed");
76                return bounded_json_response(
77                    StatusCode::SERVICE_UNAVAILABLE,
78                    &serde_json::json!({
79                        "error": "accepted-current browser provisioning unavailable"
80                    }),
81                );
82            }
83        },
84        Err(error) => {
85            tracing::warn!(error = %error, "browser provisioning failed closed");
86            return bounded_json_response(
87                StatusCode::SERVICE_UNAVAILABLE,
88                &serde_json::json!({
89                    "error": "accepted-current browser provisioning unavailable"
90                }),
91            );
92        }
93    };
94    projection_response(&document)
95}
96
97fn projection_response(
98    document: &hyprstream_rpc::browser_provisioning::BrowserProvisioningDocument,
99) -> Response {
100    bounded_json_response(StatusCode::OK, document)
101}
102
103fn bounded_json_response<T: Serialize + ?Sized>(status: StatusCode, document: &T) -> Response {
104    let body = match serde_json::to_vec(document) {
105        Ok(body) => body,
106        Err(error) => {
107            tracing::error!(error = %error, "browser projection serialization failed closed");
108            return StatusCode::SERVICE_UNAVAILABLE.into_response();
109        }
110    };
111    if body.len() > hyprstream_rpc::browser_provisioning::MAX_PROVISIONING_BYTES {
112        tracing::error!(
113            length = body.len(),
114            "browser projection exceeded the serialization bound"
115        );
116        return StatusCode::SERVICE_UNAVAILABLE.into_response();
117    }
118    let Ok(content_length) = HeaderValue::from_str(&body.len().to_string()) else {
119        return StatusCode::SERVICE_UNAVAILABLE.into_response();
120    };
121    let mut response = Response::new(axum::body::Body::from(body));
122    *response.status_mut() = status;
123    let headers = response.headers_mut();
124    headers.insert(
125        header::CONTENT_TYPE,
126        HeaderValue::from_static("application/json"),
127    );
128    headers.insert(header::CONTENT_LENGTH, content_length);
129    headers.insert(
130        header::CACHE_CONTROL,
131        HeaderValue::from_static("no-store, max-age=0"),
132    );
133    headers.insert(header::PRAGMA, HeaderValue::from_static("no-cache"));
134    response
135}
136
137#[cfg(test)]
138#[allow(clippy::expect_used)]
139mod tests {
140    use super::*;
141    use hyprstream_rpc::browser_provisioning::{
142        BrowserProvisioningDocument, BrowserProvisioningMaterial, BrowserRouteRole,
143        BrowserTransportSecurity,
144    };
145
146    #[test]
147    fn browser_carrier_query_matches_emitted_and_legacy_spelling() {
148        for profile in [
149            BrowserCarrierProfile::OwnedHybridWebTransport.as_str(),
150            "owned-hybrid-webtransport",
151        ] {
152            let uri: axum::http::Uri = format!(
153                "/.well-known/hyprstream/browser-provisioning/model?capability=hyprstream-rpc%2F1&scope=model&carrier_profile={profile}"
154            )
155            .parse()
156            .expect("valid URI");
157            let Query(query) = Query::<BrowserProvisioningQuery>::try_from_uri(&uri)
158                .expect("parse browser provisioning query");
159            assert_eq!(query.capability, "hyprstream-rpc/1");
160            assert_eq!(query.scope, "model");
161            assert_eq!(
162                query.carrier_profile,
163                BrowserCarrierProfile::OwnedHybridWebTransport
164            );
165        }
166    }
167
168    #[test]
169    fn invalid_query_context_is_rejected_before_resolver_use() {
170        let result = BrowserProvisioningRequest::new(
171            "Model",
172            "hyprstream-rpc/1",
173            "model",
174            BrowserCarrierProfile::OwnedHybridWebTransport,
175        );
176        assert!(result.is_err());
177    }
178
179    #[test]
180    fn oversized_serialized_projection_fails_closed() {
181        let response = bounded_json_response(
182            StatusCode::OK,
183            &"x".repeat(hyprstream_rpc::browser_provisioning::MAX_PROVISIONING_BYTES + 1),
184        );
185        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
186    }
187
188    #[test]
189    fn deployed_projection_response_exposes_bounded_no_store_json_headers() {
190        let signing = hyprstream_rpc::SigningKey::from_bytes(&[0x31; 32]);
191        let pq = hyprstream_rpc::node_identity::derive_mesh_mldsa_key(&signing);
192        let pq_vk = ml_dsa::Keypair::verifying_key(&pq);
193        let kem = hyprstream_rpc::node_identity::derive_mesh_kem_recipient(&signing)
194            .expect("derive KEM")
195            .public();
196        let document = BrowserProvisioningDocument::from_material(BrowserProvisioningMaterial {
197            service_name: "model".to_owned(),
198            service_did: "did:at9p:test".to_owned(),
199            service_origin: "https://model.example/".to_owned(),
200            webtransport_url: "https://model.example/hyprstream/browser-rpc".to_owned(),
201            capability: "hyprstream-rpc/1".to_owned(),
202            scope: "model".to_owned(),
203            carrier_profile: BrowserCarrierProfile::OwnedHybridWebTransport,
204            route_role: BrowserRouteRole::Origin,
205            transport_security: BrowserTransportSecurity::OwnedHybridRequired,
206            response_key_id: "did:at9p:test#response".to_owned(),
207            response_ed25519: signing.verifying_key().to_bytes(),
208            response_ml_dsa65: hyprstream_rpc::crypto::pq::ml_dsa_vk_bytes(&pq_vk),
209            request_kem_key_id: "did:at9p:test#mesh-kem".to_owned(),
210            request_kem_recipient: kem,
211            accepted_state_digest: [0x44; 64],
212            accepted_state_epoch: 1,
213            expires_at_unix_ms: 4_070_908_800_000,
214            certificate_hashes: vec![[0x55; 32]],
215            encrypted_objects_required: false,
216        })
217        .sign_projection(&signing)
218        .expect("sign projection");
219        let response = projection_response(&document);
220        let headers = response.headers();
221        assert_eq!(headers[header::CONTENT_TYPE], "application/json");
222        assert!(headers[header::CACHE_CONTROL]
223            .to_str()
224            .expect("cache header")
225            .contains("no-store"));
226        let length = headers[header::CONTENT_LENGTH]
227            .to_str()
228            .expect("length header")
229            .parse::<usize>()
230            .expect("numeric length");
231        assert!(length > 0);
232        assert!(length <= hyprstream_rpc::browser_provisioning::MAX_PROVISIONING_BYTES);
233    }
234}