1use crate::config::{TlsConfig, XetConfig};
46use crate::server::state::ResourceAuthState;
47use crate::server::tls::{resolve_rustls_config, serve_app};
48use crate::server::{middleware as server_middleware, AuthenticatedUser};
49use crate::storage::cas::{CasMount, CasMountAuthorizer, CasSubstrate, DedupDomain};
50use anyhow::Result;
51use axum::{
52 extract::{Path, State},
53 http::{header, HeaderMap, StatusCode},
54 middleware,
55 response::{IntoResponse, Response},
56 routing::{get, post},
57 Json, Router,
58};
59use hyprstream_rpc::prelude::*;
60use hyprstream_rpc::registry::SocketKind;
61use hyprstream_rpc::transport::TransportConfig;
62use hyprstream_rpc_std::registry_client::RegistryClient;
63use hyprstream_service::Spawnable;
64use hyprstream_vfs::{Mount, MountError, OREAD};
65use std::net::SocketAddr;
66use std::sync::Arc;
67use tokio::sync::Notify;
68use tracing::{info, warn};
69
70pub const SERVICE_NAME: &str = "xet";
72
73#[derive(Clone)]
75pub struct XetState {
76 pub store: CasSubstrate,
81 #[allow(dead_code)]
87 pub registry: Option<RegistryClient>,
88 pub auth: ResourceAuthState,
90 pub cas_authorizer: Arc<dyn CasMountAuthorizer>,
97}
98
99pub struct XetService {
101 config: XetConfig,
102 tls_config: TlsConfig,
103 account_config: crate::account::AccountZoneConfig,
104 state: XetState,
105}
106
107impl XetService {
108 pub fn new(
110 config: XetConfig,
111 tls_config: TlsConfig,
112 account_config: crate::account::AccountZoneConfig,
113 state: XetState,
114 ) -> Self {
115 Self {
116 config,
117 tls_config,
118 account_config,
119 state,
120 }
121 }
122
123 pub fn http_addr(&self) -> Result<SocketAddr> {
125 let addr_str = format!("{}:{}", self.config.host, self.config.port);
126 addr_str
127 .parse()
128 .map_err(|e| anyhow::anyhow!("Invalid address: {}", e))
129 }
130}
131
132pub fn create_xet_router(state: XetState) -> Router {
135 let protected_routes = Router::new()
136 .route("/get_xorb/:hash/", get(get_xorb_handler))
138 .route("/v1/reconstructions/:hash", get(reconstruction_stub))
140 .route("/v1/chunks/:key", get(chunks_stub))
141 .route("/v1/xorbs/:key", post(upload_xorb_stub))
142 .route("/v1/shards", post(upload_shard_stub))
143 .layer(middleware::from_fn_with_state(
145 state.auth.clone(),
146 server_middleware::rate_limit_middleware,
147 ))
148 .layer(middleware::from_fn_with_state(
149 state.auth.clone(),
150 server_middleware::auth_middleware,
151 ));
152
153 Router::new()
154 .route(
155 "/.well-known/oauth-protected-resource",
156 get(xet_protected_resource_metadata),
157 )
158 .merge(protected_routes)
159 .with_state(state)
160}
161
162async fn xet_protected_resource_metadata(
165 State(state): State<XetState>,
166) -> Json<crate::services::oauth::ProtectedResourceMetadata> {
167 let mut metadata = crate::services::oauth::protected_resource_metadata(
168 &state.auth.resource_url,
169 &state.auth.oauth_issuer_url,
170 );
171 metadata.resource_name = Some("HyprStream HuggingFace-XET CAS API".to_owned());
172 Json(metadata)
173}
174
175async fn get_xorb_handler(
183 State(state): State<XetState>,
184 Path(hash): Path<String>,
185 headers: HeaderMap,
186 axum::extract::Extension(user): axum::extract::Extension<AuthenticatedUser>,
187) -> Response {
188 let domain = match user.authorization_domain() {
189 Ok(domain) if domain != "*" => domain,
190 _ => return (StatusCode::FORBIDDEN, "tenant binding required").into_response(),
191 };
192 let subject = Subject::new(user.user);
193 let mount = CasMount::with_shared_authorizer(
194 state.store.clone(),
195 DedupDomain::local_default(),
196 Arc::clone(&state.cas_authorizer),
197 )
198 .with_verified_tenant(domain);
199 let mut fid = match mount.walk(&["xorb", hash.as_str()], &subject).await {
200 Ok(fid) => fid,
201 Err(e) => return mount_error_response(e, "get_xorb: mount walk failed"),
202 };
203 if let Err(e) = mount.open(&mut fid, OREAD, &subject).await {
204 return mount_error_response(e, "get_xorb: mount open failed");
205 }
206 let bytes = match mount.read(&fid, 0, u32::MAX, &subject).await {
207 Ok(b) => b,
208 Err(e) => return mount_error_response(e, "get_xorb: mount read failed"),
209 };
210
211 match parse_range(headers.get(header::RANGE), bytes.len() as u64) {
212 RangeOutcome::Full => (
213 StatusCode::OK,
214 [
215 (header::CONTENT_TYPE, "application/octet-stream".to_owned()),
216 (header::ACCEPT_RANGES, "bytes".to_owned()),
217 ],
218 bytes,
219 )
220 .into_response(),
221 RangeOutcome::Partial { start, end } => {
222 let slice = bytes[start as usize..=end as usize].to_vec();
224 let content_range = format!("bytes {start}-{end}/{}", bytes.len());
225 (
226 StatusCode::PARTIAL_CONTENT,
227 [
228 (header::CONTENT_TYPE, "application/octet-stream".to_owned()),
229 (header::ACCEPT_RANGES, "bytes".to_owned()),
230 (header::CONTENT_RANGE, content_range),
231 ],
232 slice,
233 )
234 .into_response()
235 }
236 RangeOutcome::Unsatisfiable => (
237 StatusCode::RANGE_NOT_SATISFIABLE,
238 [(header::CONTENT_RANGE, format!("bytes */{}", bytes.len()))],
239 "range not satisfiable",
240 )
241 .into_response(),
242 }
243}
244
245fn mount_error_response(err: MountError, log_message: &str) -> Response {
246 match err {
247 MountError::NotFound(_) => (StatusCode::NOT_FOUND, "xorb not found").into_response(),
248 MountError::InvalidArgument(_) => {
249 (StatusCode::BAD_REQUEST, "invalid xorb hash").into_response()
250 }
251 MountError::PermissionDenied(_) => (StatusCode::FORBIDDEN, "forbidden").into_response(),
252 other => {
253 warn!(error = %other, "{log_message}");
254 (StatusCode::INTERNAL_SERVER_ERROR, "store error").into_response()
255 }
256 }
257}
258
259enum RangeOutcome {
261 Full,
262 Partial { start: u64, end: u64 },
263 Unsatisfiable,
264}
265
266fn parse_range(header_val: Option<&axum::http::HeaderValue>, len: u64) -> RangeOutcome {
269 let raw = match header_val.and_then(|v| v.to_str().ok()) {
270 Some(s) => s,
271 None => return RangeOutcome::Full,
272 };
273 let spec = match raw.strip_prefix("bytes=") {
274 Some(s) => s.trim(),
275 None => return RangeOutcome::Full, };
277 if spec.contains(',') {
279 return RangeOutcome::Full;
280 }
281 let (start_s, end_s) = match spec.split_once('-') {
282 Some(pair) => pair,
283 None => return RangeOutcome::Full,
284 };
285
286 if len == 0 {
287 return RangeOutcome::Unsatisfiable;
288 }
289 let last = len - 1;
290
291 match (start_s.trim(), end_s.trim()) {
292 ("", n) => match n.parse::<u64>() {
294 Ok(0) => RangeOutcome::Unsatisfiable,
295 Ok(n) => {
296 let start = len.saturating_sub(n);
297 RangeOutcome::Partial { start, end: last }
298 }
299 Err(_) => RangeOutcome::Full,
300 },
301 (s, "") => match s.parse::<u64>() {
303 Ok(start) if start <= last => RangeOutcome::Partial { start, end: last },
304 Ok(_) => RangeOutcome::Unsatisfiable,
305 Err(_) => RangeOutcome::Full,
306 },
307 (s, e) => match (s.parse::<u64>(), e.parse::<u64>()) {
309 (Ok(start), Ok(end)) if start <= end && start <= last => RangeOutcome::Partial {
310 start,
311 end: end.min(last),
312 },
313 (Ok(_), Ok(_)) => RangeOutcome::Unsatisfiable,
314 _ => RangeOutcome::Full,
315 },
316 }
317}
318
319async fn reconstruction_stub(Path(_hash): Path<String>) -> Response {
334 not_implemented("reconstruction manifest: needs verified HF term/fetch_info mapping")
335}
336
337async fn chunks_stub(Path(_key): Path<String>) -> Response {
342 not_implemented("global chunk dedup query: dedup index is follow-up")
343}
344
345async fn upload_xorb_stub(Path(_key): Path<String>) -> Response {
354 not_implemented("xorb upload: xorb→putBlob(grantRepo) mapping unresolved")
355}
356
357async fn upload_shard_stub() -> Response {
362 not_implemented("shard upload: authenticated ingest mapping is follow-up")
363}
364
365fn not_implemented(reason: &str) -> Response {
367 (StatusCode::NOT_IMPLEMENTED, format!("TODO(#654): {reason}")).into_response()
368}
369
370impl Spawnable for XetService {
371 fn name(&self) -> &str {
372 SERVICE_NAME
373 }
374
375 fn registrations(&self) -> Vec<(SocketKind, TransportConfig)> {
376 Vec::new()
379 }
380
381 fn run(
382 self: Box<Self>,
383 shutdown: Arc<Notify>,
384 on_ready: Option<tokio::sync::oneshot::Sender<()>>,
385 ) -> Result<(), hyprstream_rpc::error::RpcError> {
386 let rt = tokio::runtime::Builder::new_multi_thread()
387 .enable_all()
388 .build()
389 .map_err(|e| hyprstream_rpc::error::RpcError::SpawnFailed(format!("runtime: {e}")))?;
390
391 rt.block_on(async move {
392 let addr = self.http_addr().map_err(|e| {
393 hyprstream_rpc::error::RpcError::SpawnFailed(format!("Invalid HTTP address: {e}"))
394 })?;
395
396 let rustls_config = resolve_rustls_config(
397 &self.tls_config,
398 &self.account_config,
399 self.config.tls_cert.as_ref(),
400 self.config.tls_key.as_ref(),
401 )
402 .await
403 .map_err(|e| hyprstream_rpc::error::RpcError::SpawnFailed(format!("TLS config: {e}")))?;
404
405 let scheme = if rustls_config.is_some() { "https" } else { "http" };
406 let app = create_xet_router(self.state.clone());
407
408 let audience = &self.state.auth.resource_url;
409 let issuer = &self.state.auth.oauth_issuer_url;
410 if !audience.starts_with(&format!("{scheme}://")) {
411 warn!(
412 effective_audience = %audience,
413 served_scheme = scheme,
414 "Xet JWT audience scheme differs from the HTTP transport; tokens must use the logged effective audience"
415 );
416 }
417
418 info!(
419 effective_audience = %audience,
420 oauth_issuer = %issuer,
421 "HF-XET CAS API available at {scheme}://{addr} (get_xorb implemented; other routes 501, see #654)"
422 );
423
424 if let Some(tx) = on_ready {
425 let _ = tx.send(());
426 }
427 let _ = hyprstream_rpc::notify::ready();
428
429 serve_app(addr, app, rustls_config, shutdown, "XetService").await
430 })
431 }
432}
433
434#[cfg(test)]
435#[allow(clippy::unwrap_used, clippy::expect_used)] mod tests {
437 use super::*;
438 use axum::body::Body;
439 use axum::http::Request as HttpRequest;
440 use hyprstream_rpc::auth::{
441 CompositeKeyPair, CompositeKeySet, CompositePairRole, CompositePairState, CredentialId,
442 };
443 use std::collections::HashMap;
444 use tower::ServiceExt; const AUDIENCE: &str = "http://localhost:6792";
447 const ISSUER: &str = "http://localhost:6791";
448
449 const HASH: &str = "aa00bb11cc22dd33ee44ff5566778899aabbccddeeff00112233445566778899";
451
452 struct TestIssuer {
453 ml_dsa: hyprstream_rpc::crypto::pq::MlDsaSigningKey,
454 ed25519: ed25519_dalek::SigningKey,
455 key_set: Arc<CompositeKeySet>,
456 }
457
458 impl TestIssuer {
459 fn new() -> Self {
460 let (ml_dsa, ml_dsa_vk) = hyprstream_rpc::crypto::pq::ml_dsa_generate_keypair();
461 let ed25519 = ed25519_dalek::SigningKey::generate(&mut rand::rngs::OsRng);
462 let kid = crate::auth::jwt::composite_kid(&ml_dsa_vk, &ed25519.verifying_key());
463 let pair = CompositeKeyPair::verifying(
464 kid,
465 ml_dsa_vk,
466 ed25519.verifying_key(),
467 CompositePairRole::OAuth,
468 CompositePairState::Active,
469 0,
470 i64::MAX,
471 );
472 let key_set = Arc::new(CompositeKeySet::default());
473 key_set
474 .publish(1, "xet-test-keys".to_owned(), vec![pair])
475 .unwrap();
476 Self {
477 ml_dsa,
478 ed25519,
479 key_set,
480 }
481 }
482
483 fn token(&self, audience: &str, jti: &str) -> String {
484 let now = chrono::Utc::now().timestamp();
485 let mut claims = crate::auth::jwt::Claims::new("alice".to_owned(), now, now + 3600)
486 .with_issuer(ISSUER.to_owned())
487 .with_tenant("tenant-a.example".to_owned())
488 .with_audience(Some(audience.to_owned()))
489 .with_client_id("hyprstream-oauth-client-1");
490 claims.jti = Some(jti.to_owned());
491 crate::auth::jwt::encode_composite_ml_dsa_65_ed25519(
492 &claims,
493 &self.ml_dsa,
494 &self.ed25519,
495 )
496 }
497 }
498
499 fn test_state_with_xorb(dir: &std::path::Path, hash: &str, bytes: &[u8]) -> XetState {
501 if hyprstream_rpc::auth::global_credential_revocation_store().is_none() {
506 let _ = hyprstream_rpc::auth::set_global_credential_revocation_store(Arc::new(
507 hyprstream_rpc::auth::InMemoryCredentialRevocationStore::new(),
508 ));
509 }
510 std::fs::create_dir_all(dir.join("xorbs")).unwrap();
511 std::fs::write(dir.join("xorbs").join(format!("default.{hash}")), bytes).unwrap();
512
513 let (_sk, vk) = hyprstream_rpc::crypto::generate_signing_keypair();
514 let trusted_issuers = HashMap::new();
515 let federation_resolver =
516 Arc::new(crate::auth::FederationKeyResolver::new(&trusted_issuers));
517
518 XetState {
519 store: CasSubstrate::new(dir),
520 registry: None,
522 auth: ResourceAuthState::new(
523 vk,
524 AUDIENCE.to_owned(),
525 ISSUER.to_owned(),
526 federation_resolver,
527 ),
528 cas_authorizer: Arc::new(crate::storage::cas::AllowAllCasAuthorizer),
531 }
532 }
533
534 fn with_test_issuer(mut state: XetState, issuer: &TestIssuer) -> XetState {
535 state.auth.composite_key_set = Arc::clone(&issuer.key_set);
536 state
537 }
538
539 fn authorized_request(uri: &str, token: &str) -> HttpRequest<Body> {
540 HttpRequest::builder()
541 .uri(uri)
542 .header(header::AUTHORIZATION, format!("Bearer {token}"))
543 .body(Body::empty())
544 .unwrap()
545 }
546
547 #[test]
548 fn test_service_name() {
549 assert_eq!(SERVICE_NAME, "xet");
550 }
551
552 #[test]
553 fn does_not_advertise_an_unserved_rpc_endpoint() {
554 let dir = tempfile::tempdir().unwrap();
555 let state = test_state_with_xorb(dir.path(), HASH, b"x");
556 let service = XetService::new(
557 XetConfig::default(),
558 TlsConfig::default(),
559 crate::account::AccountZoneConfig::default(),
560 state,
561 );
562 assert!(service.registrations().is_empty());
563 }
564
565 #[test]
566 fn config_has_no_second_enable_switch() {
567 let serialized = serde_json::to_value(XetConfig::default()).unwrap();
568 assert!(serialized.get("enabled").is_none());
569 }
570
571 #[test]
572 fn configured_external_url_is_the_effective_audience() {
573 let config = XetConfig {
574 external_url: Some("https://xet.example.test/cas".to_owned()),
575 ..XetConfig::default()
576 };
577 assert_eq!(config.resource_url(), "https://xet.example.test/cas");
578 }
579
580 #[tokio::test]
581 async fn get_xorb_happy_path_returns_bytes() {
582 let dir = tempfile::tempdir().unwrap();
583 let payload = b"xorb-payload-bytes";
584 let state = test_state_with_xorb(dir.path(), HASH, payload);
585
586 let resp = get_xorb_handler(
587 State(state),
588 Path(HASH.to_owned()),
589 HeaderMap::new(),
590 axum::extract::Extension(AuthenticatedUser {
591 user: "alice".to_owned(),
592 verified_tenant: Some("tenant-a.example".to_owned()),
593 token: None,
594 exp: None,
595 }),
596 )
597 .await;
598
599 assert_eq!(resp.status(), StatusCode::OK);
600 let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
601 .await
602 .unwrap();
603 assert_eq!(&body[..], payload);
604 }
605
606 #[tokio::test]
607 async fn get_xorb_honors_range() {
608 let dir = tempfile::tempdir().unwrap();
609 let payload = b"0123456789";
610 let state = test_state_with_xorb(dir.path(), HASH, payload);
611
612 let mut headers = HeaderMap::new();
613 headers.insert(header::RANGE, "bytes=2-5".parse().unwrap());
614 let resp = get_xorb_handler(
615 State(state),
616 Path(HASH.to_owned()),
617 headers,
618 axum::extract::Extension(AuthenticatedUser {
619 user: "alice".to_owned(),
620 verified_tenant: Some("tenant-a.example".to_owned()),
621 token: None,
622 exp: None,
623 }),
624 )
625 .await;
626
627 assert_eq!(resp.status(), StatusCode::PARTIAL_CONTENT);
628 let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
629 .await
630 .unwrap();
631 assert_eq!(&body[..], b"2345");
632 }
633
634 #[tokio::test]
635 async fn unauthenticated_request_is_rejected() {
636 let dir = tempfile::tempdir().unwrap();
637 let state = test_state_with_xorb(dir.path(), HASH, b"x");
638 let app = create_xet_router(state);
639
640 let resp = app
641 .oneshot(
642 HttpRequest::builder()
643 .uri(format!("/get_xorb/{HASH}/"))
644 .body(Body::empty())
645 .unwrap(),
646 )
647 .await
648 .unwrap();
649
650 assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
651 assert_eq!(
652 resp.headers()
653 .get(header::WWW_AUTHENTICATE)
654 .unwrap()
655 .to_str()
656 .unwrap(),
657 format!("Bearer resource_metadata=\"{AUDIENCE}/.well-known/oauth-protected-resource\"")
658 );
659 }
660
661 #[tokio::test]
662 async fn wrong_audience_token_is_rejected() {
663 let dir = tempfile::tempdir().unwrap();
664 let issuer = TestIssuer::new();
665 let state = with_test_issuer(test_state_with_xorb(dir.path(), HASH, b"x"), &issuer);
666 let token = issuer.token("https://wrong.example/resource", "wrong-aud");
667
668 let resp = create_xet_router(state)
669 .oneshot(authorized_request(&format!("/get_xorb/{HASH}/"), &token))
670 .await
671 .unwrap();
672
673 assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
674 }
675
676 #[tokio::test]
677 async fn revoked_jti_is_rejected() {
678 let dir = tempfile::tempdir().unwrap();
679 let issuer = TestIssuer::new();
680 let state = with_test_issuer(test_state_with_xorb(dir.path(), HASH, b"x"), &issuer);
681 if hyprstream_rpc::auth::global_credential_revocation_store().is_none() {
685 let _ = hyprstream_rpc::auth::set_global_credential_revocation_store(Arc::new(
686 hyprstream_rpc::auth::InMemoryCredentialRevocationStore::new(),
687 ));
688 }
689 let cred_id = CredentialId::jwt(ISSUER, "revoked-xet");
690 hyprstream_rpc::auth::global_credential_revocation_store()
691 .expect("global store must be set")
692 .revoke_credential(cred_id, chrono::Utc::now().timestamp() + 3600)
693 .await
694 .expect("in-memory revocation publication cannot fail");
695 let token = issuer.token(AUDIENCE, "revoked-xet");
696
697 let resp = create_xet_router(state)
698 .oneshot(authorized_request(&format!("/get_xorb/{HASH}/"), &token))
699 .await
700 .unwrap();
701
702 assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
703 }
704
705 #[tokio::test]
706 async fn shared_subject_rate_limit_is_enforced() {
707 let dir = tempfile::tempdir().unwrap();
708 let issuer = TestIssuer::new();
709 let mut state = with_test_issuer(test_state_with_xorb(dir.path(), HASH, b"x"), &issuer);
710 state.auth.rate_limiter = Arc::new(server_middleware::RateLimiter::new(1, 60));
711 let app = create_xet_router(state);
712
713 let first = app
714 .clone()
715 .oneshot(authorized_request(
716 &format!("/v1/reconstructions/{HASH}"),
717 &issuer.token(AUDIENCE, "rate-1"),
718 ))
719 .await
720 .unwrap();
721 assert_eq!(first.status(), StatusCode::NOT_IMPLEMENTED);
722
723 let second = app
724 .oneshot(authorized_request(
725 &format!("/v1/reconstructions/{HASH}"),
726 &issuer.token(AUDIENCE, "rate-2"),
727 ))
728 .await
729 .unwrap();
730 assert_eq!(second.status(), StatusCode::TOO_MANY_REQUESTS);
731 }
732
733 #[tokio::test]
734 async fn protected_resource_metadata_is_public_and_xet_specific() {
735 let dir = tempfile::tempdir().unwrap();
736 let state = test_state_with_xorb(dir.path(), HASH, b"x");
737
738 let resp = create_xet_router(state)
739 .oneshot(
740 HttpRequest::builder()
741 .uri("/.well-known/oauth-protected-resource")
742 .body(Body::empty())
743 .unwrap(),
744 )
745 .await
746 .unwrap();
747
748 assert_eq!(resp.status(), StatusCode::OK);
749 let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
750 .await
751 .unwrap();
752 let metadata: crate::services::oauth::ProtectedResourceMetadata =
753 serde_json::from_slice(&body).unwrap();
754 assert_eq!(metadata.resource, AUDIENCE);
755 assert_eq!(metadata.authorization_servers, vec![ISSUER]);
756 assert_eq!(
757 metadata.resource_name.as_deref(),
758 Some("HyprStream HuggingFace-XET CAS API")
759 );
760 }
761
762 #[tokio::test]
763 async fn stub_routes_return_501_when_authorized_shape() {
764 let resp = reconstruction_stub(Path(HASH.to_owned())).await;
767 assert_eq!(resp.status(), StatusCode::NOT_IMPLEMENTED);
768 let resp = upload_xorb_stub(Path("k".to_owned())).await;
769 assert_eq!(resp.status(), StatusCode::NOT_IMPLEMENTED);
770 let resp = upload_shard_stub().await;
771 assert_eq!(resp.status(), StatusCode::NOT_IMPLEMENTED);
772 }
773}