1use crate::error::RuntimeResult;
8use crate::{KhiveRuntime, NamespaceToken};
9use khive_channel::VerifiedRecipientReceipt;
10use khive_db::stores::note::transport::SenderTransportStore;
11pub use khive_db::stores::note::transport::{
12 EnvelopeKey, FailureClass, HoldReason, PolicyMode, SenderAssurance, SenderEnvelope,
13 SenderRecord, TransportState,
14};
15
16#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
19#[serde(rename_all = "snake_case")]
20pub enum TransportStatus {
21 Pending,
22 RecipientStored,
23 RecipientQuarantined,
24 Failed,
25 Unknown,
26}
27
28pub fn sender_transport_insert_statement(
34 token: &NamespaceToken,
35 mut envelope: SenderEnvelope,
36) -> RuntimeResult<khive_storage::SqlStatement> {
37 envelope.namespace = token.namespace().as_str().to_owned();
38 envelope.sender_assurance = SenderAssurance::Claimed;
39 Ok(khive_db::stores::note::transport::sender_envelope_insert_statement(&envelope)?)
40}
41
42impl KhiveRuntime {
43 fn sender_transport_store(&self) -> SenderTransportStore {
44 SenderTransportStore::new(self.backend().pool_arc())
45 }
46 pub async fn sender_transport_status(
49 &self,
50 token: &NamespaceToken,
51 outbound_note_id: uuid::Uuid,
52 ) -> RuntimeResult<TransportStatus> {
53 let Some(row) = self
54 .sender_transport_store()
55 .get_by_outbound_note_id(token.namespace().as_str(), outbound_note_id)
56 .await?
57 else {
58 return Ok(TransportStatus::Unknown);
59 };
60 if row.hold_reason.is_some() {
61 return Ok(TransportStatus::Pending);
62 }
63 Ok(match row.state {
64 TransportState::Pending => TransportStatus::Pending,
65 TransportState::RecipientStored => TransportStatus::RecipientStored,
66 TransportState::RecipientQuarantined => TransportStatus::RecipientQuarantined,
67 TransportState::Failed => TransportStatus::Failed,
68 })
69 }
70 pub async fn create_sender_transport(
75 &self,
76 token: &NamespaceToken,
77 mut envelope: SenderEnvelope,
78 ) -> RuntimeResult<SenderRecord> {
79 envelope.namespace = token.namespace().as_str().to_owned();
80 envelope.sender_assurance = SenderAssurance::Claimed;
81 Ok(self
82 .sender_transport_store()
83 .create(envelope, false)
84 .await?)
85 }
86 pub async fn reencrypt_sender_transport_after_confirmed_key_change(
91 &self,
92 token: &NamespaceToken,
93 mut envelope: SenderEnvelope,
94 ) -> RuntimeResult<SenderRecord> {
95 envelope.namespace = token.namespace().as_str().to_owned();
96 envelope.sender_assurance = SenderAssurance::Claimed;
97 Ok(self.sender_transport_store().create(envelope, true).await?)
98 }
99 pub async fn sender_transport(&self, key: EnvelopeKey) -> RuntimeResult<Option<SenderRecord>> {
101 Ok(self.sender_transport_store().get(key).await?)
102 }
103 pub async fn current_sender_transport(
107 &self,
108 token: &NamespaceToken,
109 kind: &str,
110 slug: &str,
111 logical_id: uuid::Uuid,
112 ) -> RuntimeResult<Option<SenderRecord>> {
113 Ok(self
114 .sender_transport_store()
115 .current_by_logical_id(token.namespace().as_str(), kind, slug, logical_id)
116 .await?)
117 }
118 pub async fn pending_sender_transports(
121 &self,
122 token: &NamespaceToken,
123 kind: &str,
124 slug: &str,
125 now: i64,
126 limit: u32,
127 ) -> RuntimeResult<Vec<SenderRecord>> {
128 Ok(self
129 .sender_transport_store()
130 .list_pending(token.namespace().as_str(), kind, slug, now, limit)
131 .await?)
132 }
133 pub async fn record_sender_transport_admission(
136 &self,
137 key: EnvelopeKey,
138 admitted_at: chrono::DateTime<chrono::Utc>,
139 ) -> RuntimeResult<()> {
140 Ok(self
141 .sender_transport_store()
142 .record_admission(key, admitted_at.timestamp_micros())
143 .await?)
144 }
145 pub async fn record_sender_transport_failure(
148 &self,
149 key: EnvelopeKey,
150 class: FailureClass,
151 next_retry_at: Option<i64>,
152 ) -> RuntimeResult<()> {
153 Ok(self
154 .sender_transport_store()
155 .record_failure(key, class, next_retry_at)
156 .await?)
157 }
158 pub async fn hold_sender_transport(
162 &self,
163 key: EnvelopeKey,
164 reason: Option<HoldReason>,
165 ) -> RuntimeResult<()> {
166 Ok(self.sender_transport_store().hold(key, reason).await?)
167 }
168 pub async fn accept_verified_recipient_receipt(
196 &self,
197 key: EnvelopeKey,
198 state: TransportState,
199 receipt: VerifiedRecipientReceipt,
200 ) -> RuntimeResult<()> {
201 let receipt = serde_json::to_value(receipt.receipt()).map_err(|error| {
202 crate::RuntimeError::InvalidInput(format!("invalid receipt: {error}"))
203 })?;
204 Ok(self
205 .sender_transport_store()
206 .accept_receipt(key, state, receipt)
207 .await?)
208 }
209}
210
211#[cfg(test)]
212mod tests {
213 use super::*;
214 use khive_channel::{
215 receipt_signing_input, DeliveryReceipt, DeliveryReceiptBinding, ReceiptDisposition,
216 };
217 use ring::signature::{Ed25519KeyPair, KeyPair};
218 use uuid::Uuid;
219
220 fn signed_receipt(
221 mut receipt: DeliveryReceipt,
222 seed: &[u8; 32],
223 ) -> (DeliveryReceipt, [u8; 32]) {
224 let key_pair = Ed25519KeyPair::from_seed_unchecked(seed).unwrap();
225 let input = receipt_signing_input(&receipt).unwrap();
226 receipt.signature = key_pair.sign(&input).as_ref().to_vec();
227 let pinned_key = key_pair.public_key().as_ref().try_into().unwrap();
228 (receipt, pinned_key)
229 }
230
231 fn envelope() -> SenderEnvelope {
232 SenderEnvelope {
233 namespace: "untrusted-envelope-attribution".into(),
234 logical_message_id: Uuid::new_v4(),
235 outbound_note_id: Uuid::new_v4(),
236 kind: "khive".into(),
237 slug: "device".into(),
238 credential_ref: "keys/device".into(),
239 recipient_address: format!("khive1:example/{}", Uuid::nil()),
240 protocol_version: 1,
241 sender_agent_id: Uuid::new_v4().to_string(),
242 sender_assurance: SenderAssurance::DaemonBearer,
243 recipient_agent_id: Uuid::nil().to_string(),
244 recipient_device_id: Uuid::new_v4(),
245 recipient_key_epoch: 1,
246 contact_generation: 1,
247 sender_key_epoch: 1,
248 recipient_key_fingerprint: "ab".repeat(32),
249 enc: vec![1; 32],
250 ciphertext: vec![2, 0, 255],
251 }
252 }
253
254 #[tokio::test]
255 async fn verified_receipt_uses_bound_backend_and_token_attribution() {
256 let runtime = KhiveRuntime::memory().unwrap();
257 let unrelated = KhiveRuntime::memory().unwrap();
258 let token = NamespaceToken::local();
259 let envelope = envelope();
260 let key = envelope.key();
261 let stored = runtime
262 .create_sender_transport(&token, envelope.clone())
263 .await
264 .unwrap();
265 assert_eq!(stored.envelope.namespace, token.namespace().as_str());
266 assert_eq!(stored.envelope.sender_assurance, SenderAssurance::Claimed);
267 assert_eq!(
268 runtime
269 .sender_transport(key)
270 .await
271 .unwrap()
272 .unwrap()
273 .envelope
274 .sender_assurance,
275 SenderAssurance::Claimed
276 );
277 assert!(
278 unrelated.sender_transport(key).await.unwrap().is_none(),
279 "transport must use bound backend"
280 );
281 let hold = HoldReason::PolicyDenied {
282 mode: PolicyMode::Enforce,
283 revision: 7,
284 };
285 let admitted_at = chrono::Utc::now();
286 runtime
287 .record_sender_transport_admission(key, admitted_at)
288 .await
289 .unwrap();
290 let admitted = runtime.sender_transport(key).await.unwrap().unwrap();
291 assert_eq!(admitted.admitted_at, Some(admitted_at.timestamp_micros()));
292 assert_eq!(
293 admitted.next_retry_at,
294 Some(admitted_at.timestamp_micros() + 600_000_000)
295 );
296 runtime
297 .hold_sender_transport(key, Some(hold))
298 .await
299 .unwrap();
300 assert_eq!(
301 runtime
302 .sender_transport(key)
303 .await
304 .unwrap()
305 .unwrap()
306 .hold_reason,
307 Some(hold)
308 );
309 let receipt = DeliveryReceipt {
310 binding: DeliveryReceiptBinding {
311 protocol_version: 1,
312 logical_message_id: envelope.logical_message_id,
313 sender_agent_id: envelope.sender_agent_id,
314 recipient_agent_id: envelope.recipient_agent_id,
315 recipient_device_id: envelope.recipient_device_id,
316 recipient_key_epoch: 1,
317 contact_generation: 1,
318 delivery_attempt_id: Uuid::new_v4(),
319 },
320 disposition: ReceiptDisposition::Stored,
321 signature: vec![7],
322 };
323 let (receipt, pinned_key) = signed_receipt(receipt, &[19; 32]);
324 assert!(runtime
325 .accept_verified_recipient_receipt(
326 key,
327 TransportState::RecipientQuarantined,
328 VerifiedRecipientReceipt::verify(receipt.clone(), &pinned_key).unwrap()
329 )
330 .await
331 .is_err());
332 runtime
333 .accept_verified_recipient_receipt(
334 key,
335 TransportState::RecipientStored,
336 VerifiedRecipientReceipt::verify(receipt, &pinned_key).unwrap(),
337 )
338 .await
339 .unwrap();
340 assert_eq!(
341 runtime
342 .sender_transport(key)
343 .await
344 .unwrap()
345 .unwrap()
346 .hold_reason,
347 None
348 );
349 assert_eq!(
350 runtime.sender_transport(key).await.unwrap().unwrap().state,
351 TransportState::RecipientStored
352 );
353 }
354 #[tokio::test]
355 async fn caller_sender_assurance_is_claimed() {
356 for assurance in [
357 SenderAssurance::DaemonBearer,
358 SenderAssurance::ActorSignature,
359 ] {
360 let runtime = KhiveRuntime::memory().unwrap();
361 let token = NamespaceToken::local();
362 let mut envelope = envelope();
363 envelope.sender_assurance = assurance;
364 let first = runtime
365 .create_sender_transport(&token, envelope.clone())
366 .await
367 .unwrap();
368 assert_eq!(
369 first.envelope.sender_assurance,
370 SenderAssurance::Claimed,
371 "create must normalize caller assurance"
372 );
373 assert_eq!(
374 runtime.sender_transport(envelope.key()).await.unwrap(),
375 Some(first)
376 );
377 runtime
378 .hold_sender_transport(envelope.key(), Some(HoldReason::RecipientKeyChanged))
379 .await
380 .unwrap();
381 envelope.recipient_key_epoch += 1;
382 let next = runtime
383 .reencrypt_sender_transport_after_confirmed_key_change(&token, envelope.clone())
384 .await
385 .expect("re-encryption must normalize caller assurance");
386 assert_eq!(next.envelope.sender_assurance, SenderAssurance::Claimed);
387 assert_eq!(
388 runtime.sender_transport(envelope.key()).await.unwrap(),
389 Some(next)
390 );
391 }
392 }
393
394 async fn accept_status_receipt(
395 runtime: &KhiveRuntime,
396 envelope: &SenderEnvelope,
397 disposition: ReceiptDisposition,
398 ) {
399 let state = match disposition {
400 ReceiptDisposition::Stored => TransportState::RecipientStored,
401 ReceiptDisposition::Quarantined => TransportState::RecipientQuarantined,
402 };
403 let receipt = DeliveryReceipt {
404 binding: DeliveryReceiptBinding {
405 protocol_version: envelope.protocol_version,
406 logical_message_id: envelope.logical_message_id,
407 sender_agent_id: envelope.sender_agent_id.clone(),
408 recipient_agent_id: envelope.recipient_agent_id.clone(),
409 recipient_device_id: envelope.recipient_device_id,
410 recipient_key_epoch: envelope.recipient_key_epoch,
411 contact_generation: envelope.contact_generation,
412 delivery_attempt_id: Uuid::new_v4(),
413 },
414 disposition,
415 signature: vec![],
416 };
417 let (receipt, pinned_key) = signed_receipt(receipt, &[23; 32]);
418 runtime
419 .accept_verified_recipient_receipt(
420 envelope.key(),
421 state,
422 VerifiedRecipientReceipt::verify(receipt, &pinned_key).unwrap(),
423 )
424 .await
425 .unwrap();
426 }
427
428 #[tokio::test]
429 async fn transport_status_pending_admission_and_hold() {
430 let runtime = KhiveRuntime::memory().unwrap();
431 let token = NamespaceToken::local();
432 let e = envelope();
433 runtime
434 .create_sender_transport(&token, e.clone())
435 .await
436 .unwrap();
437 assert_eq!(
438 runtime
439 .sender_transport_status(&token, e.outbound_note_id)
440 .await
441 .unwrap(),
442 TransportStatus::Pending,
443 "a newly persisted envelope is pending"
444 );
445 runtime
446 .record_sender_transport_admission(e.key(), chrono::Utc::now())
447 .await
448 .unwrap();
449 assert_eq!(
450 runtime
451 .sender_transport_status(&token, e.outbound_note_id)
452 .await
453 .unwrap(),
454 TransportStatus::Pending,
455 "service admission is not recipient storage"
456 );
457 runtime
458 .hold_sender_transport(e.key(), Some(HoldReason::InsufficientCredit))
459 .await
460 .unwrap();
461 assert_eq!(
462 runtime
463 .sender_transport_status(&token, e.outbound_note_id)
464 .await
465 .unwrap(),
466 TransportStatus::Pending,
467 "an insufficient-credit hold is pending, never a further status"
468 );
469 }
470
471 #[tokio::test]
472 async fn transport_status_failed_and_verified_receipts() {
473 let runtime = KhiveRuntime::memory().unwrap();
474 let token = NamespaceToken::local();
475 for (disposition, expected) in [
476 (ReceiptDisposition::Stored, TransportStatus::RecipientStored),
477 (
478 ReceiptDisposition::Quarantined,
479 TransportStatus::RecipientQuarantined,
480 ),
481 ] {
482 let e = envelope();
483 runtime
484 .create_sender_transport(&token, e.clone())
485 .await
486 .unwrap();
487 runtime
488 .record_sender_transport_failure(e.key(), FailureClass::Permanent, None)
489 .await
490 .unwrap();
491 assert_eq!(
492 runtime
493 .sender_transport_status(&token, e.outbound_note_id)
494 .await
495 .unwrap(),
496 TransportStatus::Failed,
497 "a permanent local refusal is failed"
498 );
499 accept_status_receipt(&runtime, &e, disposition).await;
500 assert_eq!(
501 runtime
502 .sender_transport_status(&token, e.outbound_note_id)
503 .await
504 .unwrap(),
505 expected,
506 "a verified receipt supersedes the local failure"
507 );
508 }
509 assert_eq!(
510 runtime
511 .sender_transport_status(&token, Uuid::new_v4())
512 .await
513 .unwrap(),
514 TransportStatus::Unknown,
515 "an absent outbound UUID is unknown"
516 );
517 }
518
519 #[tokio::test]
520 async fn transport_status_is_primary_namespace_and_backend_scoped() {
521 let runtime = KhiveRuntime::memory().unwrap();
522 let token_a = NamespaceToken::for_namespace(crate::Namespace::parse("sender-a").unwrap());
523 let token_b = NamespaceToken::mint_with_visibility(
524 crate::Namespace::parse("sender-b").unwrap(),
525 vec![crate::Namespace::parse("sender-a").unwrap()],
526 crate::ActorRef::anonymous(),
527 );
528 let e = envelope();
529 runtime
530 .create_sender_transport(&token_a, e.clone())
531 .await
532 .unwrap();
533 assert_eq!(
534 runtime
535 .sender_transport(e.key())
536 .await
537 .unwrap()
538 .unwrap()
539 .envelope
540 .namespace,
541 "sender-a"
542 );
543 assert_eq!(
544 runtime
545 .sender_transport_status(&token_a, e.outbound_note_id)
546 .await
547 .unwrap(),
548 TransportStatus::Pending
549 );
550 assert_eq!(
551 runtime
552 .sender_transport_status(&token_b, e.outbound_note_id)
553 .await
554 .unwrap(),
555 TransportStatus::Unknown,
556 "additional visible namespaces cannot reveal transport status"
557 );
558 let unrelated = KhiveRuntime::memory().unwrap();
559 assert_eq!(
560 unrelated
561 .sender_transport_status(&token_a, e.outbound_note_id)
562 .await
563 .unwrap(),
564 TransportStatus::Unknown,
565 "a different bound backend has no record"
566 );
567 }
568
569 #[tokio::test]
570 async fn transport_status_read_preserves_every_sender_field() {
571 let runtime = KhiveRuntime::memory().unwrap();
572 let token = NamespaceToken::local();
573 let e = envelope();
574 runtime
575 .create_sender_transport(&token, e.clone())
576 .await
577 .unwrap();
578 let before = runtime.sender_transport(e.key()).await.unwrap().unwrap();
579 assert_eq!(before.admitted_at, None);
580 for _ in 0..3 {
581 assert_eq!(
582 runtime
583 .sender_transport_status(&token, e.outbound_note_id)
584 .await
585 .unwrap(),
586 TransportStatus::Pending
587 );
588 }
589 let after = runtime.sender_transport(e.key()).await.unwrap().unwrap();
590 assert_eq!(
591 after, before,
592 "a status read preserves envelope bytes, holds, attempts and timestamps"
593 );
594 }
595}