Skip to main content

khive_runtime/
comm_transport.rs

1//! Runtime-owned sender transport persistence (ADR-105).
2//!
3//! Call these methods on the runtime bound to comm's assigned backend, exactly
4//! as for ordinary comm note operations. Routing happens before this boundary;
5//! the adapter never opens a database or supplies SQL. Receipt signatures are
6//! checked against the owner's pinned recipient key before durable state changes.
7use 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/// Sender-local delivery status, including the absence of a transport record.
17/// Holds retain `Pending`; `Unknown` is never persisted as a transport state.
18#[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
28/// Build the sender transport INSERT for a first envelope as one statement, so the caller can
29/// commit it in the same atomic unit as the outbound note. Namespace and sender assurance are
30/// normalized exactly as [`KhiveRuntime::create_sender_transport`] does: the namespace comes from
31/// the token and assurance stays claimed. The envelope's `outbound_note_id` must already name the
32/// note the statement is committed beside.
33pub 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    /// Read transport status in the token's primary namespace on the bound backend.
47    /// This does not infer the internal inbound sibling or mutate retry metadata.
48    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    /// Persist immutable bytes before first submission. An exact retry is a no-op;
71    /// a different envelope with the same identity is refused. The namespace is
72    /// caller attribution and is always taken from the token. Sender assurance
73    /// is claimed until authenticated verification is available.
74    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    /// Re-encrypt only after the caller confirms the recipient key change. The
87    /// old record must be on a key-change hold, and the new epoch must increase.
88    /// Cryptographic construction and directory confirmation belong to the caller.
89    /// Caller-supplied assurance is normalized to claimed as on initial creation.
90    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    /// Read by durable identity. Absence means unknown; unknown is not persisted.
100    pub async fn sender_transport(&self, key: EnvelopeKey) -> RuntimeResult<Option<SenderRecord>> {
101        Ok(self.sender_transport_store().get(key).await?)
102    }
103    /// The current envelope for one logical message: the row with the highest envelope
104    /// sequence, whatever its state. Absence means unknown. The namespace comes from the
105    /// token, so a caller cannot read another namespace's transport rows.
106    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    /// Due unheld submissions for the exact configured kind and slug. Times use
119    /// Unix microseconds; choosing the backoff and jitter is the caller's job.
120    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    /// Record service admission time and schedule resubmission 600 seconds later.
134    /// The timestamp is stored as Unix microseconds and survives restarts.
135    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    /// Record a failed attempt. Authentication errors remain pending and do not
146    /// advance the attempt count. This never modifies the envelope bytes.
147    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    /// Set/release credit or policy holds, or set a key-change hold. A policy hold
159    /// carries the evaluated mode and revision. Key-change holds can only be
160    /// superseded through explicit confirmed re-encryption.
161    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    /// Accept an already signature-verified recipient receipt, including after a
169    /// local failure. Every known binding field and target disposition must match
170    /// durable data. This method performs no signature verification itself.
171    ///
172    /// An unverified payload cannot cross this boundary:
173    ///
174    /// ```compile_fail
175    /// use khive_channel::DeliveryReceipt;
176    /// use khive_runtime::{KhiveRuntime, comm_transport::{EnvelopeKey, TransportState}};
177    /// async fn accept(runtime: &KhiveRuntime, key: EnvelopeKey, receipt: DeliveryReceipt) {
178    ///     runtime.accept_verified_recipient_receipt(key, TransportState::RecipientStored, receipt)
179    ///         .await.unwrap();
180    /// }
181    /// ```
182    ///
183    /// Its positive twin uses the channel constructor and the same runtime method:
184    ///
185    /// ```
186    /// use khive_channel::{DeliveryReceipt, VerifiedRecipientReceipt};
187    /// use khive_runtime::{KhiveRuntime, comm_transport::{EnvelopeKey, TransportState}};
188    /// async fn accept(runtime: &KhiveRuntime, key: EnvelopeKey, receipt: DeliveryReceipt,
189    ///     pinned_key: &[u8; 32]) {
190    ///     let verified = VerifiedRecipientReceipt::verify(receipt, pinned_key).unwrap();
191    ///     runtime.accept_verified_recipient_receipt(key, TransportState::RecipientStored, verified)
192    ///         .await.unwrap();
193    /// }
194    /// ```
195    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}