1use anyhow::{anyhow, ensure, Context, Result};
12use git2::Repository;
13use hyprstream_rpc::transport_traits::is_pre_dispatch_transport_error;
14use hyprstream_rpc_std::policy_client::{PolicyCheck, PolicyClient};
15use hyprstream_rpc_std::registry_client::{RegisterRequest, RegistryClient};
16use std::future::Future;
17use std::io::Write;
18use std::path::{Path, PathBuf};
19use std::time::Duration;
20
21const CANARY_NAME: &str = "canary";
22const POLICY_CHECK_TIMEOUT: Duration = Duration::from_secs(10);
23const REGISTRY_LOOKUP_TIMEOUT: Duration = Duration::from_secs(15);
24const REGISTRY_REGISTER_TIMEOUT: Duration = Duration::from_secs(30);
25const REGISTRY_SERVICE_SUBJECT: &str = "service:registry";
26
27pub fn require_registry_service_subject(jwt: &str) -> Result<()> {
32 use base64::Engine as _;
33
34 let payload = jwt
35 .split('.')
36 .nth(1)
37 .ok_or_else(|| anyhow!("service credential subject mismatch"))?;
38 let decoded = base64::engine::general_purpose::URL_SAFE_NO_PAD
39 .decode(payload)
40 .map_err(|_| anyhow!("service credential subject mismatch"))?;
41 let claims: serde_json::Value = serde_json::from_slice(&decoded)
42 .map_err(|_| anyhow!("service credential subject mismatch"))?;
43 ensure!(
44 claims.get("sub").and_then(serde_json::Value::as_str) == Some(REGISTRY_SERVICE_SUBJECT),
45 "service credential subject mismatch"
46 );
47 Ok(())
48}
49
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51enum FailureCategory {
52 PolicyDenied,
53 PolicyCheckInconclusive,
54 PreDispatchTransportFailure,
55 DispatchStatusUnclassified,
56}
57
58impl FailureCategory {
59 fn as_str(self) -> &'static str {
60 match self {
61 Self::PolicyDenied => "policy_denied",
62 Self::PolicyCheckInconclusive => "policy_check_inconclusive",
63 Self::PreDispatchTransportFailure => "pre_dispatch_transport_failure",
64 Self::DispatchStatusUnclassified => "dispatch_status_unclassified",
65 }
66 }
67}
68
69#[derive(Debug)]
70struct ReadbackInconclusive(FailureCategory);
71
72#[derive(Debug)]
73struct RegisterOutcomeUnconfirmed;
74
75impl std::fmt::Display for RegisterOutcomeUnconfirmed {
76 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
77 f.write_str("Registry canary registration unconfirmed")
78 }
79}
80
81impl std::error::Error for RegisterOutcomeUnconfirmed {}
82
83impl std::fmt::Display for ReadbackInconclusive {
84 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
85 f.write_str("Registry canary readback inconclusive")
86 }
87}
88
89impl std::error::Error for ReadbackInconclusive {}
90
91pub fn error_category(error: &anyhow::Error) -> &'static str {
94 error
95 .chain()
96 .find_map(|cause| {
97 cause
98 .downcast_ref::<ReadbackInconclusive>()
99 .map(|failure| failure.0.as_str())
100 })
101 .unwrap_or("setup_or_preflight_unclassified")
102}
103
104pub fn registration_error_category(error: &anyhow::Error) -> &'static str {
107 if error
108 .chain()
109 .any(<dyn std::error::Error + 'static>::is::<RegisterOutcomeUnconfirmed>)
110 {
111 "registration_unconfirmed"
112 } else {
113 error_category(error)
114 }
115}
116
117#[derive(Debug, PartialEq, Eq)]
118struct PreparedCanary {
119 path: PathBuf,
120 oid: String,
121 #[cfg(unix)]
122 device: u64,
123 #[cfg(unix)]
124 inode: u64,
125}
126
127fn prepare_canary(base: &Path, path: &Path, expected_head: &str) -> Result<PreparedCanary> {
128 ensure!(
129 expected_head.len() == 40
130 && expected_head
131 .bytes()
132 .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()),
133 "expected HEAD must be a full lowercase Git SHA-1 OID"
134 );
135 ensure!(path.is_absolute(), "canary path must be absolute");
136 let metadata = path.symlink_metadata().context("stat canary path")?;
137 ensure!(
138 metadata.is_dir() && !metadata.file_type().is_symlink(),
139 "canary path must be a real directory"
140 );
141 let base = base.canonicalize().context("canonical Registry base")?;
142 let canonical = path.canonicalize().context("canonical canary path")?;
143 ensure!(canonical == path, "canary path must be canonical");
144 ensure!(
145 canonical.parent() == Some(base.as_path()),
146 "canary must be a direct child of Registry base"
147 );
148 let git_dir = canonical.join(".git");
149 let git_metadata = git_dir
150 .symlink_metadata()
151 .context("stat canary Git metadata")?;
152 ensure!(
153 git_metadata.is_dir() && !git_metadata.file_type().is_symlink(),
154 "canary Git metadata must be a real directory inside the selected path"
155 );
156 let repo = Repository::open(&canonical).context("open existing canary Git repository")?;
157 let workdir = repo
158 .workdir()
159 .ok_or_else(|| anyhow!("bare canary repository is unsupported"))?;
160 ensure!(
161 workdir.canonicalize()? == canonical,
162 "canary path is not its Git worktree root"
163 );
164 let head = repo.head()?;
165 ensure!(
166 head.name() == Some("refs/heads/main"),
167 "canary HEAD must track main"
168 );
169 let oid = head.peel_to_commit()?.id().to_string();
170 ensure!(
171 oid == expected_head,
172 "canary HEAD differs from reviewed OID"
173 );
174 Ok(PreparedCanary {
175 path: canonical,
176 oid,
177 #[cfg(unix)]
178 device: std::os::unix::fs::MetadataExt::dev(&metadata),
179 #[cfg(unix)]
180 inode: std::os::unix::fs::MetadataExt::ino(&metadata),
181 })
182}
183
184fn canary_registration_request(prepared: &PreparedCanary) -> Result<RegisterRequest> {
185 let path = prepared
186 .path
187 .to_str()
188 .ok_or_else(|| anyhow!("Canary path must be UTF-8"))?
189 .to_owned();
190 Ok(RegisterRequest {
191 path,
192 name: CANARY_NAME.to_owned(),
193 tracking_ref: "main".to_owned(),
194 })
195}
196
197pub async fn readback_local_canary(
202 policy: &PolicyClient,
203 registry: &RegistryClient,
204 service_jwt: &str,
205 base: &Path,
206 path: &Path,
207 expected_head: &str,
208) -> Result<()> {
209 require_registry_service_subject(service_jwt)
210 .map_err(|_| anyhow!("Registry service credential preflight failed"))?;
211 let prepared = prepare_canary(base, path, expected_head)
212 .map_err(|_| anyhow!("Registry canary readback preflight failed"))?;
213 let request = PolicyCheck {
214 subject: "service:registry".to_owned(),
215 domain: "*".to_owned(),
216 resource: "registry:canary".to_owned(),
217 operation: "query".to_owned(),
218 };
219 let readback = policy_gated_lookup(
220 POLICY_CHECK_TIMEOUT,
221 policy
222 .clone()
223 .with_delegated_bearer(service_jwt.to_owned())
224 .check(&request),
225 || async {
226 bounded_registry_lookup(REGISTRY_LOOKUP_TIMEOUT, registry.get_by_name(CANARY_NAME))
227 .await
228 },
229 )
230 .await?;
231 ensure!(
232 canary_readback_matches(
233 &readback.id,
234 &readback.name,
235 &readback.url,
236 &readback.current_oid,
237 &prepared,
238 ),
239 "Registry canary readback mismatch"
240 );
241 let stdout = std::io::stdout();
242 let mut output = stdout.lock();
243 serde_json::to_writer(
244 &mut output,
245 &serde_json::json!({
246 "name": CANARY_NAME,
247 "repoId": readback.id,
248 "commit": prepared.oid,
249 "found": true,
250 "pdsRecordVerified": false
251 }),
252 )?;
253 output.write_all(b"\n")?;
254 Ok(())
255}
256
257pub async fn register_local_canary(
261 policy: &PolicyClient,
262 registry: &RegistryClient,
263 service_jwt: &str,
264 base: &Path,
265 path: &Path,
266 expected_head: &str,
267) -> Result<()> {
268 require_registry_service_subject(service_jwt)
269 .map_err(|_| anyhow!("Registry service credential preflight failed"))?;
270 let prepared = prepare_canary(base, path, expected_head)
271 .map_err(|_| anyhow!("Registry canary registration preflight failed"))?;
272 let write_check = PolicyCheck {
273 subject: REGISTRY_SERVICE_SUBJECT.to_owned(),
274 domain: "*".to_owned(),
275 resource: "registry:Register".to_owned(),
276 operation: "write".to_owned(),
277 };
278 let query_check = PolicyCheck {
279 subject: REGISTRY_SERVICE_SUBJECT.to_owned(),
280 domain: "*".to_owned(),
281 resource: "registry:canary".to_owned(),
282 operation: "query".to_owned(),
283 };
284 let delegated_policy = policy.clone().with_delegated_bearer(service_jwt.to_owned());
285 let request = canary_registration_request(&prepared)?;
286 let returned = policy_gated_registration(
287 POLICY_CHECK_TIMEOUT,
288 delegated_policy.check(&write_check),
289 delegated_policy.check(&query_check),
290 || async {
291 bounded_registry_register(REGISTRY_REGISTER_TIMEOUT, registry.register(&request)).await
292 },
293 )
294 .await?;
295 let readback =
296 bounded_registry_lookup(REGISTRY_LOOKUP_TIMEOUT, registry.get_by_name(CANARY_NAME))
297 .await
298 .map_err(|_| RegisterOutcomeUnconfirmed)?;
299 let unchanged = prepare_canary(base, path, expected_head)
300 .map(|current| current == prepared)
301 .unwrap_or(false);
302 if !unchanged
303 || !canary_readback_matches(
304 &returned.id,
305 &returned.name,
306 &returned.url,
307 &returned.current_oid,
308 &prepared,
309 )
310 || !canary_readback_matches(
311 &readback.id,
312 &readback.name,
313 &readback.url,
314 &readback.current_oid,
315 &prepared,
316 )
317 || returned.id != readback.id
318 {
319 return Err(RegisterOutcomeUnconfirmed.into());
320 }
321 let stdout = std::io::stdout();
322 let mut output = stdout.lock();
323 serde_json::to_writer(
324 &mut output,
325 &serde_json::json!({
326 "name": CANARY_NAME,
327 "repoId": returned.id,
328 "commit": prepared.oid,
329 "registered": true,
330 "pdsRecordVerified": false,
331 }),
332 )?;
333 output.write_all(b"\n")?;
334 Ok(())
335}
336
337async fn bounded_policy_check(
338 timeout: Duration,
339 check: impl Future<Output = Result<bool>>,
340) -> Result<bool> {
341 match tokio::time::timeout(timeout, check).await {
342 Ok(Ok(allowed)) => Ok(allowed),
343 Ok(Err(_)) | Err(_) => {
344 Err(ReadbackInconclusive(FailureCategory::PolicyCheckInconclusive).into())
345 }
346 }
347}
348
349async fn bounded_registry_lookup<T>(
350 timeout: Duration,
351 lookup: impl Future<Output = Result<T>>,
352) -> Result<T> {
353 match tokio::time::timeout(timeout, lookup).await {
354 Ok(Ok(found)) => Ok(found),
355 Ok(Err(error)) => {
356 let category = if is_pre_dispatch_transport_error(&error) {
357 FailureCategory::PreDispatchTransportFailure
358 } else {
359 FailureCategory::DispatchStatusUnclassified
362 };
363 Err(ReadbackInconclusive(category).into())
364 }
365 Err(_) => Err(ReadbackInconclusive(FailureCategory::DispatchStatusUnclassified).into()),
367 }
368}
369
370async fn bounded_registry_register<T>(
371 timeout: Duration,
372 register: impl Future<Output = Result<T>>,
373) -> Result<T> {
374 match tokio::time::timeout(timeout, register).await {
375 Ok(Ok(registered)) => Ok(registered),
376 Ok(Err(_)) | Err(_) => Err(RegisterOutcomeUnconfirmed.into()),
377 }
378}
379
380fn canary_readback_matches(
381 id: &str,
382 name: &str,
383 url: &str,
384 current_oid: &str,
385 prepared: &PreparedCanary,
386) -> bool {
387 uuid::Uuid::parse_str(id).is_ok()
388 && name == CANARY_NAME
389 && url == format!("file://{}", prepared.path.display())
390 && current_oid == prepared.oid
391}
392
393async fn policy_gated_lookup<T, P, F, Fut>(
394 timeout: Duration,
395 policy_check: P,
396 lookup: F,
397) -> Result<T>
398where
399 P: Future<Output = Result<bool>>,
400 F: FnOnce() -> Fut,
401 Fut: Future<Output = Result<T>>,
402{
403 let allowed = bounded_policy_check(timeout, policy_check).await?;
404 if !allowed {
405 return Err(ReadbackInconclusive(FailureCategory::PolicyDenied).into());
406 }
407 lookup().await
408}
409
410async fn policy_gated_registration<T, P, Q, F, Fut>(
411 timeout: Duration,
412 write_check: P,
413 query_check: Q,
414 register: F,
415) -> Result<T>
416where
417 P: Future<Output = Result<bool>>,
418 Q: Future<Output = Result<bool>>,
419 F: FnOnce() -> Fut,
420 Fut: Future<Output = Result<T>>,
421{
422 if !bounded_policy_check(timeout, write_check).await? {
423 return Err(ReadbackInconclusive(FailureCategory::PolicyDenied).into());
424 }
425 if !bounded_policy_check(timeout, query_check).await? {
426 return Err(ReadbackInconclusive(FailureCategory::PolicyDenied).into());
427 }
428 register().await
429}
430
431#[cfg(test)]
432mod tests {
433 #![allow(clippy::unwrap_used, clippy::expect_used)]
434
435 use super::{
436 bounded_registry_lookup, bounded_registry_register, canary_readback_matches,
437 error_category, policy_gated_lookup, policy_gated_registration,
438 registration_error_category, require_registry_service_subject, PreparedCanary,
439 };
440 use base64::Engine as _;
441 use git2::{Repository, Signature};
442 use std::path::Path;
443 use std::sync::{
444 atomic::{AtomicUsize, Ordering},
445 Arc,
446 };
447 use std::time::Duration;
448
449 #[tokio::test]
450 async fn denied_policy_preflight_makes_zero_registry_calls() {
451 let calls = Arc::new(AtomicUsize::new(0));
452 let observed = Arc::clone(&calls);
453 let result =
454 policy_gated_lookup(Duration::from_secs(1), async { Ok(false) }, || async move {
455 observed.fetch_add(1, Ordering::SeqCst);
456 Ok::<_, anyhow::Error>("must not run")
457 })
458 .await
459 .unwrap_err();
460 assert_eq!(error_category(&result), "policy_denied");
461 assert_eq!(calls.load(Ordering::SeqCst), 0);
462 }
463
464 #[tokio::test]
465 async fn policy_preflight_error_makes_zero_registry_calls_and_hides_detail() {
466 let calls = Arc::new(AtomicUsize::new(0));
467 let observed = Arc::clone(&calls);
468 let result = policy_gated_lookup(
469 Duration::from_secs(1),
470 async { Err(anyhow::anyhow!("secret-bearing policy endpoint detail")) },
471 || async move {
472 observed.fetch_add(1, Ordering::SeqCst);
473 Ok::<_, anyhow::Error>("must not run")
474 },
475 )
476 .await
477 .unwrap_err();
478 assert_eq!(error_category(&result), "policy_check_inconclusive");
479 assert!(!result.to_string().contains("secret-bearing"));
480 assert_eq!(calls.load(Ordering::SeqCst), 0);
481 }
482
483 #[tokio::test]
484 async fn allowed_policy_preflight_calls_registry_exactly_once() {
485 let calls = Arc::new(AtomicUsize::new(0));
486 let observed = Arc::clone(&calls);
487 let value =
488 policy_gated_lookup(Duration::from_secs(1), async { Ok(true) }, || async move {
489 observed.fetch_add(1, Ordering::SeqCst);
490 Ok::<_, anyhow::Error>("one lookup")
491 })
492 .await
493 .expect("allowed lookup");
494 assert_eq!(value, "one lookup");
495 assert_eq!(calls.load(Ordering::SeqCst), 1);
496 }
497
498 #[tokio::test]
499 async fn registration_requires_both_grants_before_the_single_write() {
500 let checks = Arc::new(AtomicUsize::new(0));
501 let writes = Arc::new(AtomicUsize::new(0));
502 for (write_allowed, query_allowed, expected_checks, expected_writes) in
503 [(false, true, 1, 0), (true, false, 2, 0), (true, true, 2, 1)]
504 {
505 checks.store(0, Ordering::SeqCst);
506 writes.store(0, Ordering::SeqCst);
507 let first = Arc::clone(&checks);
508 let second = Arc::clone(&checks);
509 let recorded_write = Arc::clone(&writes);
510 let result = policy_gated_registration(
511 Duration::from_secs(1),
512 async move {
513 first.fetch_add(1, Ordering::SeqCst);
514 Ok(write_allowed)
515 },
516 async move {
517 second.fetch_add(1, Ordering::SeqCst);
518 Ok(query_allowed)
519 },
520 || async move {
521 recorded_write.fetch_add(1, Ordering::SeqCst);
522 Ok::<_, anyhow::Error>(())
523 },
524 )
525 .await;
526 assert_eq!(checks.load(Ordering::SeqCst), expected_checks);
527 assert_eq!(writes.load(Ordering::SeqCst), expected_writes);
528 if expected_writes == 0 {
529 assert_eq!(error_category(&result.unwrap_err()), "policy_denied");
530 } else {
531 assert!(result.is_ok());
532 }
533 }
534 }
535
536 #[tokio::test]
537 async fn failed_registration_is_unconfirmed_and_hides_rpc_detail() {
538 let result = bounded_registry_register(Duration::from_secs(1), async {
539 Err::<(), _>(anyhow::anyhow!("private endpoint and credential detail"))
540 })
541 .await
542 .unwrap_err();
543 assert_eq!(
544 registration_error_category(&result),
545 "registration_unconfirmed"
546 );
547 assert!(!result.to_string().contains("private endpoint"));
548
549 let timed_out = bounded_registry_register(Duration::from_millis(10), async {
550 tokio::time::sleep(Duration::from_secs(1)).await;
551 Ok::<_, anyhow::Error>(())
552 })
553 .await
554 .unwrap_err();
555 assert_eq!(
556 registration_error_category(&timed_out),
557 "registration_unconfirmed"
558 );
559 }
560
561 #[tokio::test]
562 async fn policy_preflight_timeout_makes_zero_registry_calls() {
563 let calls = Arc::new(AtomicUsize::new(0));
564 let observed = Arc::clone(&calls);
565 let result = policy_gated_lookup(
566 Duration::from_millis(10),
567 async {
568 tokio::time::sleep(Duration::from_secs(1)).await;
569 Ok(true)
570 },
571 || async move {
572 observed.fetch_add(1, Ordering::SeqCst);
573 Ok::<_, anyhow::Error>("must not run")
574 },
575 )
576 .await
577 .unwrap_err();
578 assert_eq!(error_category(&result), "policy_check_inconclusive");
579 assert_eq!(calls.load(Ordering::SeqCst), 0);
580 }
581
582 #[tokio::test]
583 async fn lookup_not_found_or_error_remains_inconclusive() {
584 let result = bounded_registry_lookup(Duration::from_secs(1), async {
585 Err::<(), _>(anyhow::anyhow!("Repository not found"))
586 })
587 .await
588 .unwrap_err();
589 assert_eq!(error_category(&result), "dispatch_status_unclassified");
590 assert!(!result.to_string().contains("not found"));
591 }
592
593 #[test]
594 fn service_credential_subject_guard_accepts_only_registry_sub_without_printing_claims() {
595 fn fixture(claims: serde_json::Value) -> String {
596 let encoded = base64::engine::general_purpose::URL_SAFE_NO_PAD
597 .encode(serde_json::to_vec(&claims).expect("serialize synthetic claims"));
598 format!("header.{encoded}.signature")
599 }
600
601 assert!(require_registry_service_subject(&fixture(
602 serde_json::json!({"sub":"service:registry"})
603 ))
604 .is_ok());
605 for token in [
606 fixture(serde_json::json!({"sub":"service:model"})),
607 fixture(serde_json::json!({"sub":"user:alice"})),
608 fixture(serde_json::json!({"iss":"https://issuer.invalid"})),
609 "malformed".to_owned(),
610 ] {
611 let error = require_registry_service_subject(&token).unwrap_err();
612 assert_eq!(error.to_string(), "service credential subject mismatch");
613 assert!(!error.to_string().contains("service:model"));
614 }
615 }
616
617 #[test]
618 fn canary_readback_requires_exact_reviewed_entry() {
619 let prepared = PreparedCanary {
620 path: "/var/lib/hyprstream/models/canary".into(),
621 oid: "3f1d3a63258e132cd06314b736445a8bab13b9bd".into(),
622 #[cfg(unix)]
623 device: 1,
624 #[cfg(unix)]
625 inode: 1,
626 };
627 assert!(canary_readback_matches(
628 "2f0cf08f-6330-44e5-9fad-0e3896d8f566",
629 "canary",
630 "file:///var/lib/hyprstream/models/canary",
631 &prepared.oid,
632 &prepared,
633 ));
634 assert!(!canary_readback_matches(
635 "2f0cf08f-6330-44e5-9fad-0e3896d8f566",
636 "canary",
637 "file:///other/canary",
638 &prepared.oid,
639 &prepared,
640 ));
641 }
642
643 #[test]
644 fn preflight_binds_canonical_repo_and_expected_head() -> anyhow::Result<()> {
645 let root = tempfile::tempdir()?;
646 let path = root.path().join("canary");
647 let repo = Repository::init(&path)?;
648 repo.set_head("refs/heads/main")?;
649 std::fs::write(path.join("README.md"), "canary\n")?;
650 let mut index = repo.index()?;
651 index.add_path(Path::new("README.md"))?;
652 index.write()?;
653 let tree = repo.find_tree(index.write_tree()?)?;
654 let author = Signature::now("Canary", "canary@example.invalid")?;
655 let oid = repo.commit(Some("HEAD"), &author, &author, "canary", &tree, &[])?;
656 let expected = oid.to_string();
657 let prepared = super::prepare_canary(root.path(), &path, &expected)?;
658 let request = super::canary_registration_request(&prepared)?;
659 assert_eq!(request.path, path.to_str().unwrap());
660 assert_eq!(request.name, "canary");
661 assert_eq!(request.tracking_ref, "main");
662 assert!(super::prepare_canary(root.path(), &path, &"0".repeat(40)).is_err());
663 assert!(
664 super::prepare_canary(root.path(), &root.path().join("missing"), &expected).is_err()
665 );
666 repo.branch("other", &repo.find_commit(oid)?, false)?;
667 repo.set_head("refs/heads/other")?;
668 assert!(super::prepare_canary(root.path(), &path, &expected).is_err());
669 Ok(())
670 }
671}