lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

commit 2ed3db9de1d9fb789b40ffb88e335a3681540c9c
parent 530c923997f4d586e53477fc385ab11219d88931
Author: triesap <tyson@radroots.org>
Date:   Tue, 27 Oct 2026 16:10:12 +0000

execution: share obtained private envelopes across work scopes

- Separate bounded signed outers and temporary keys from chat work metadata.
- Bind original work at the command owner and preserve native containment.
- Update native and browser I/O with explicit generated API declarations.
- Verify exact retention, faults, native bindings and packed browser calls.

Diffstat:
Mcontracts/api_baselines/radroots_execution.txt | 2+-
Mcontracts/api_baselines/radroots_storage.txt | 14++++++++++++++
Mcrates/execution/src/session/command.rs | 16+++++++++++-----
Mcrates/radroots/src/native_commands.rs | 11+++++------
Mcrates/radroots/src/native_commerce_tests.rs | 8++++++--
Mcrates/radroots/tests/support/receipt_delivery_validation.rs | 53++++++++++++++++++++++++++++++++++++++++++++++++++++-
Mcrates/radroots_browser/src/commands.rs | 11+++++------
Mcrates/storage/src/command.rs | 2+-
Mcrates/storage/src/command/delivery.rs | 53+++++++++++++++++++++++++----------------------------
Acrates/storage/src/command/delivery/private.rs | 88+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
10 files changed, 208 insertions(+), 50 deletions(-)

diff --git a/contracts/api_baselines/radroots_execution.txt b/contracts/api_baselines/radroots_execution.txt @@ -11,8 +11,8 @@ pub fn radroots_execution::session::command::CommandRuntime::new(alloc::sync::Ar pub trait radroots_execution::session::command::CommandIo: radroots_execution::session::HostBound pub fn radroots_execution::session::command::CommandIo::delivery_id(&self) -> core::result::Result<alloc::string::String, radroots_storage::command::OperationError> pub fn radroots_execution::session::command::CommandIo::enabled(&self) -> bool -pub fn radroots_execution::session::command::CommandIo::envelope(&self, radroots_storage::command::installation::PublicationWork, &str) -> core::result::Result<radroots_storage::command::delivery::EnvelopeCandidate, radroots_storage::command::OperationError> pub fn radroots_execution::session::command::CommandIo::now(&self) -> core::result::Result<radroots_domain::context::UnixSeconds, radroots_storage::command::OperationError> +pub fn radroots_execution::session::command::CommandIo::private_envelope(&self, radroots_identity::key::PublicKey, &str) -> core::result::Result<radroots_storage::command::delivery::private::PrivateEnvelopeCandidate, radroots_storage::command::OperationError> pub fn radroots_execution::session::command::CommandIo::public_targets(&self) -> core::result::Result<radroots_transport::target::TargetSet, radroots_storage::command::OperationError> pub fn radroots_execution::session::command::CommandIo::publication_policy(&self) -> radroots_transport::policy::SatisfactionPolicy pub fn radroots_execution::session::command::CommandIo::publish(&self, radroots_transport::sink::DeliveryRequest, radroots_transport::target::TargetSet) -> radroots_execution::session::HostFuture<'_, core::result::Result<radroots_transport::sink::DeliveryReceipt, radroots_transport::sink::SinkFailure>> diff --git a/contracts/api_baselines/radroots_storage.txt b/contracts/api_baselines/radroots_storage.txt @@ -1078,6 +1078,7 @@ pub const fn radroots_storage::command::EnvelopeCandidate::created_at(&self) -> pub const fn radroots_storage::command::EnvelopeCandidate::digest(&self) -> &[u8; 32] pub const fn radroots_storage::command::EnvelopeCandidate::event_id(&self) -> radroots_domain::identifier::EnvelopeEventId pub fn radroots_storage::command::EnvelopeCandidate::from_obtained(radroots_storage::command::PublicationWork, &str, &[u8; 32]) -> core::result::Result<Self, radroots_storage::command::OperationError> +pub fn radroots_storage::command::EnvelopeCandidate::from_private(radroots_storage::command::PublicationWork, radroots_storage::command::PrivateEnvelopeCandidate) -> core::result::Result<Self, radroots_storage::command::OperationError> pub fn radroots_storage::command::EnvelopeCandidate::raw_json(&self) -> &str pub fn radroots_storage::command::EnvelopeCandidate::retained_copy(&self) -> Self pub fn radroots_storage::command::EnvelopeCandidate::with_wrapping_key<T>(&self, impl core::ops::function::FnOnce(&[u8; 32]) -> T) -> T @@ -1156,6 +1157,19 @@ pub const fn radroots_storage::command::PreparedOperation::revision(&self) -> ra pub const fn radroots_storage::command::PreparedOperation::transaction_id(&self) -> radroots_domain::identifier::TransactionId impl core::fmt::Debug for radroots_storage::command::PreparedOperation pub fn radroots_storage::command::PreparedOperation::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_storage::command::PrivateEnvelopeCandidate +impl radroots_storage::command::PrivateEnvelopeCandidate +pub const fn radroots_storage::command::PrivateEnvelopeCandidate::author(&self) -> radroots_identity::key::PublicKey +pub const fn radroots_storage::command::PrivateEnvelopeCandidate::created_at(&self) -> radroots_domain::context::UnixSeconds +pub const fn radroots_storage::command::PrivateEnvelopeCandidate::digest(&self) -> &[u8; 32] +pub const fn radroots_storage::command::PrivateEnvelopeCandidate::event_id(&self) -> radroots_domain::identifier::EnvelopeEventId +pub fn radroots_storage::command::PrivateEnvelopeCandidate::from_obtained(radroots_identity::key::PublicKey, &str, &[u8; 32]) -> core::result::Result<Self, radroots_storage::command::OperationError> +pub fn radroots_storage::command::PrivateEnvelopeCandidate::raw_json(&self) -> &str +pub const fn radroots_storage::command::PrivateEnvelopeCandidate::recipient(&self) -> radroots_identity::key::PublicKey +pub fn radroots_storage::command::PrivateEnvelopeCandidate::retained_copy(&self) -> Self +pub fn radroots_storage::command::PrivateEnvelopeCandidate::with_wrapping_key<T>(&self, impl core::ops::function::FnOnce(&[u8; 32]) -> T) -> T +impl core::fmt::Debug for radroots_storage::command::PrivateEnvelopeCandidate +pub fn radroots_storage::command::PrivateEnvelopeCandidate::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result pub struct radroots_storage::command::PublicPublicationWork impl radroots_storage::command::PublicPublicationWork pub const fn radroots_storage::command::PublicPublicationWork::evidence(&self) -> radroots_storage::command::EvidenceReceipt diff --git a/crates/execution/src/session/command.rs b/crates/execution/src/session/command.rs @@ -27,7 +27,7 @@ use radroots_storage::{ BoundSigningPlan, ClaimAttemptOutcome, ClaimAttemptRequest, DeliveryAttemptOutcome, DeliveryAttemptRequest, DeliveryIntent, DeliveryObservation, EnvelopeCandidate, EvidenceCaptureOutcome, InstallationRequest, OperationError, OperationJournal, - PlanBindingOutcome, PreparedOperation, PublicationArtifact, PublicationWork, + PlanBindingOutcome, PreparedOperation, PrivateEnvelopeCandidate, PublicationArtifact, }, workspace::{AttachmentProof, WorkspaceBinding}, }; @@ -61,11 +61,11 @@ pub trait CommandIo: HostBound { /// Explicit relay acceptance criterion, frozen by the first retained D. fn publication_policy(&self) -> radroots_transport::policy::SatisfactionPolicy; /// Wraps the original obtained seal with a fresh temporary envelope key. - fn envelope( + fn private_envelope( &self, - work: PublicationWork, + recipient: PublicKey, raw_seal: &str, - ) -> Result<EnvelopeCandidate, OperationError>; + ) -> Result<PrivateEnvelopeCandidate, OperationError>; /// Fresh full-width transport-attempt identity from qualified entropy. fn delivery_id(&self) -> Result<String, OperationError>; /// Dispatches only an actual freshly committed original delivery claim. @@ -623,7 +623,13 @@ impl CommandRuntime { .await? .ok_or(OperationError::RecoveryRequired)?; let envelope = if original.is_none() { - Some(self.io.envelope(private, captured.evidence().raw_json())?) + Some(EnvelopeCandidate::from_private( + private, + self.io.private_envelope( + private.recipient(), + captured.evidence().raw_json(), + )?, + )?) } else { None }; diff --git a/crates/radroots/src/native_commands.rs b/crates/radroots/src/native_commands.rs @@ -10,7 +10,7 @@ use radroots_nostr::signing::{ }; use radroots_protocol::nip59::CapturedDmRoute; use radroots_signing::provider::NonceSource; -use radroots_storage::command::{EnvelopeCandidate, OperationError, PublicationWork}; +use radroots_storage::command::{OperationError, PrivateEnvelopeCandidate}; use radroots_transport::{ EventSink, EventSource, TargetSet, policy::{SatisfactionClass, SatisfactionPolicy}, @@ -145,17 +145,16 @@ impl CommandIo for NativeCommands { fn publication_policy(&self) -> SatisfactionPolicy { self.policy.clone() } - fn envelope( + fn private_envelope( &self, - work: PublicationWork, + recipient: PublicKey, raw_seal: &str, - ) -> Result<EnvelopeCandidate, OperationError> { + ) -> Result<PrivateEnvelopeCandidate, OperationError> { let now = NonZeroU64::new(self.now()?.get()).ok_or(OperationError::RecoveryRequired)?; - let recipient = work.recipient(); let wrapped = wrap_retained_seal(raw_seal, recipient, now, &OsNonceSource) .map_err(|_| OperationError::InvalidEvidence)?; wrapped.with_wrapping_key(|key| { - EnvelopeCandidate::from_obtained(work, wrapped.signed_json(), key) + PrivateEnvelopeCandidate::from_obtained(recipient, wrapped.signed_json(), key) }) } fn delivery_id(&self) -> Result<String, OperationError> { diff --git a/crates/radroots/src/native_commerce_tests.rs b/crates/radroots/src/native_commerce_tests.rs @@ -35,7 +35,7 @@ use radroots_signing::{ signer::BoxFuture, }; use radroots_storage::{ - command::{EnvelopeCandidate, OperationError, PublicationWork}, + command::{OperationError, PrivateEnvelopeCandidate}, event::SourceGeneration, inventory::{InventoryCheckpointRef, InventoryOutcome, InventoryRequest, InventoryStore}, workspace::{ @@ -268,7 +268,11 @@ impl CommandIo for Io { fn publication_policy(&self) -> radroots_transport::policy::SatisfactionPolicy { panic!("acceptance does not start D") } - fn envelope(&self, _: PublicationWork, _: &str) -> Result<EnvelopeCandidate, OperationError> { + fn private_envelope( + &self, + _: PublicKey, + _: &str, + ) -> Result<PrivateEnvelopeCandidate, OperationError> { panic!("acceptance does not wrap") } fn delivery_id(&self) -> Result<String, OperationError> { diff --git a/crates/radroots/tests/support/receipt_delivery_validation.rs b/crates/radroots/tests/support/receipt_delivery_validation.rs @@ -1,7 +1,9 @@ //! Untrusted data projections must not bypass the retained native graph. use super::*; use radroots_domain::TransactionId; -use radroots_storage::command::{DeliveryAttemptSummary, OperationSnapshot}; +use radroots_storage::command::{ + DeliveryAttemptSummary, OperationSnapshot, PrivateEnvelopeCandidate, +}; use radroots_transport::{ Target, TransportId, outcome::DeliveryOutcome, sink::DeliveryTargetReceipt, target::TargetScope, }; @@ -187,6 +189,51 @@ async fn snapshot(ready: &Ready) -> OperationSnapshot { } #[tokio::test] +async fn work_independent_envelope_binds_original_recipient_and_retains_exact_native_bytes() { + let ready = Ready::new(&[String::from("ws://127.0.0.1:9")], 245).await; + let obtained = ready.candidate.with_wrapping_key(|key| { + PrivateEnvelopeCandidate::from_obtained( + ready.work.recipient(), + ready.candidate.raw_json(), + key, + ) + .unwrap() + }); + let copied = obtained.retained_copy(); + drop(obtained); + let bound = EnvelopeCandidate::from_private(ready.work, copied).unwrap(); + let DeliveryAttemptOutcome::Claimed(retained) = ready + .store + .prepare_delivery_attempt(ready.request(1), copy(&ready.proof), Some(&bound)) + .await + .unwrap() + else { + panic!("actual original envelope must be retained before transport"); + }; + assert_eq!(retained.raw_json(), ready.candidate.raw_json()); + assert_eq!(retained.intent().event_id(), bound.event_id()); + assert_eq!( + ready + .query(&ready.store, retained.intent().request_id()) + .await + .raw_json(), + bound.raw_json() + ); + assert_ne!(ready.work.recipient(), key()); + let foreign = PrivateEnvelopeCandidate::from_obtained( + key(), + &outer_variant(&ready, 1059, retained.retained_at().get(), Some(1)), + &[3; 32], + ) + .unwrap(); + assert!(matches!( + EnvelopeCandidate::from_private(ready.work, foreign), + Err(OperationError::InvalidEvidence) + )); + ready.store.close().await.unwrap(); +} + +#[tokio::test] async fn malformed_carriers_and_reconstructed_attempts_cannot_replace_original_native_bytes() { let ready = Ready::new(&[String::from("ws://127.0.0.1:9")], 246).await; let retained = ready.retain(1).await; @@ -201,6 +248,10 @@ async fn malformed_carriers_and_reconstructed_attempts_cannot_replace_original_n outer_variant(&ready, 1059, time, Some(1)), ] { assert!(matches!( + PrivateEnvelopeCandidate::from_obtained(ready.work.recipient(), &raw, &wrapping_key), + Err(OperationError::InvalidEvidence) + )); + assert!(matches!( EnvelopeCandidate::from_obtained(ready.work, &raw, &wrapping_key), Err(OperationError::InvalidEvidence) )); diff --git a/crates/radroots_browser/src/commands.rs b/crates/radroots_browser/src/commands.rs @@ -7,7 +7,7 @@ use radroots_execution::session::{ use radroots_nostr::signing::gift_wrap::{randomized_past_time, wrap_retained_seal}; use radroots_protocol::nip59::CapturedDmRoute; use radroots_signing::provider::{NonceSource, ProviderError}; -use radroots_storage::command::{EnvelopeCandidate, OperationError, PublicationWork}; +use radroots_storage::command::{OperationError, PrivateEnvelopeCandidate}; use radroots_transport::{ EventSink, EventSource, TargetSet, policy::{SatisfactionClass, SatisfactionPolicy}, @@ -149,17 +149,16 @@ impl CommandIo for BrowserCommands { fn publication_policy(&self) -> SatisfactionPolicy { self.policy.clone() } - fn envelope( + fn private_envelope( &self, - work: PublicationWork, + recipient: PublicKey, raw_seal: &str, - ) -> Result<EnvelopeCandidate, OperationError> { + ) -> Result<PrivateEnvelopeCandidate, OperationError> { let now = NonZeroU64::new(self.now()?.get()).ok_or(OperationError::RecoveryRequired)?; - let recipient = work.recipient(); let wrapped = wrap_retained_seal(raw_seal, recipient, now, &BrowserNonceSource) .map_err(|_| OperationError::InvalidEvidence)?; wrapped.with_wrapping_key(|key| { - EnvelopeCandidate::from_obtained(work, wrapped.signed_json(), key) + PrivateEnvelopeCandidate::from_obtained(recipient, wrapped.signed_json(), key) }) } fn delivery_id(&self) -> Result<String, OperationError> { diff --git a/crates/storage/src/command.rs b/crates/storage/src/command.rs @@ -26,7 +26,7 @@ pub use publication::PublicationArtifact; mod snapshot; pub use delivery::{ DeliveryAttempt, DeliveryAttemptOutcome, DeliveryAttemptRequest, DeliveryIntent, - EnvelopeCandidate, + EnvelopeCandidate, PrivateEnvelopeCandidate, }; pub use delivery_summary::DeliveryAttemptSummary; pub use dm_source::SignedDmRelaySource; diff --git a/crates/storage/src/command/delivery.rs b/crates/storage/src/command/delivery.rs @@ -21,6 +21,9 @@ use sha2::{Digest, Sha256}; use std::{boxed::Box, collections::BTreeSet, string::String, vec, vec::Vec}; use zeroize::Zeroizing; +mod private; +pub use self::private::PrivateEnvelopeCandidate; + const SIGNED_MAX_BYTES: usize = 65_536; const MAX_TIME: u64 = 253_402_300_799; @@ -93,12 +96,7 @@ fn payload(raw: &str, work: PublicationArtifact) -> Result<SignedEvent, Operatio /// signature proves neither original-seal containment nor an actual store link. pub struct EnvelopeCandidate { work: PublicationWork, - event: EnvelopeEventId, - author: PublicKey, - created_at: UnixSeconds, - digest: [u8; 32], - raw: Zeroizing<String>, - key: Zeroizing<[u8; 32]>, + envelope: PrivateEnvelopeCandidate, } impl EnvelopeCandidate { /// Bounds before copying and verifies the exact one-recipient outer carrier. @@ -109,17 +107,21 @@ impl EnvelopeCandidate { raw: &str, wrapping_key: &[u8; 32], ) -> Result<Self, OperationError> { - let carrier = outer(raw, work.recipient())?; - Ok(Self { + Self::from_private( work, - event: EnvelopeEventId::from_bytes(*carrier.envelope().id().as_bytes()), - author: *carrier.envelope().author(), - created_at: UnixSeconds::new(carrier.envelope().created_at_u64()) - .map_err(|_| OperationError::InvalidEvidence)?, - digest: Sha256::digest(raw.as_bytes()).into(), - raw: Zeroizing::new(String::from(raw)), - key: Zeroizing::new(*wrapping_key), - }) + PrivateEnvelopeCandidate::from_obtained(work.recipient(), raw, wrapping_key)?, + ) + } + /// Binds a work-independent candidate to its reported original recipient. + /// The store must still authenticate the work and exact inner containment. + pub fn from_private( + work: PublicationWork, + envelope: PrivateEnvelopeCandidate, + ) -> Result<Self, OperationError> { + if envelope.recipient() != work.recipient() { + return Err(OperationError::InvalidEvidence); + } + Ok(Self { work, envelope }) } /// Reported original work; a getter does not authenticate backend state. pub const fn work(&self) -> PublicationWork { @@ -127,39 +129,34 @@ impl EnvelopeCandidate { } /// Actual signed outer event identity, separate from the original seal. pub const fn event_id(&self) -> EnvelopeEventId { - self.event + self.envelope.event_id() } /// Actual outer author; native capture must prove this temporary key. pub const fn author(&self) -> PublicKey { - self.author + self.envelope.author() } /// Signed randomized outer time, not a grant or trusted clock observation. pub const fn created_at(&self) -> UnixSeconds { - self.created_at + self.envelope.created_at() } /// SHA-256 of the exact original outer representation. pub const fn digest(&self) -> &[u8; 32] { - &self.digest + self.envelope.digest() } /// Exact obtained bytes for protected handling; never diagnostic output. pub fn raw_json(&self) -> &str { - &self.raw + self.envelope.raw_json() } /// Scoped borrow for native containment verification only. pub fn with_wrapping_key<T>(&self, verify: impl FnOnce(&[u8; 32]) -> T) -> T { - verify(&self.key) + self.envelope.with_wrapping_key(verify) } /// Explicit bounded owner copy; the caller retains its original until the /// actual outcome is reconciled. This creates no persistence fact. pub fn retained_copy(&self) -> Self { Self { work: self.work, - event: self.event, - author: self.author, - created_at: self.created_at, - digest: self.digest, - raw: Zeroizing::new(String::from(self.raw_json())), - key: Zeroizing::new(*self.key), + envelope: self.envelope.retained_copy(), } } } diff --git a/crates/storage/src/command/delivery/private.rs b/crates/storage/src/command/delivery/private.rs @@ -0,0 +1,88 @@ +//! One obtained private outer, independent of a business-work descriptor. +use super::{OperationError, outer}; +use core::fmt; +use radroots_domain::{EnvelopeEventId, PublicKey, UnixSeconds}; +use sha2::{Digest, Sha256}; +use std::string::String; +use zeroize::Zeroizing; + +/// Bounded signed NIP-59 outer and temporary wrapping material. A verified +/// carrier proves no inner containment, installation, grant or transport right. +/// Every concrete owner must verify these against its actual retained work. +pub struct PrivateEnvelopeCandidate { + recipient: PublicKey, + event: EnvelopeEventId, + author: PublicKey, + created_at: UnixSeconds, + digest: [u8; 32], + raw: Zeroizing<String>, + key: Zeroizing<[u8; 32]>, +} +impl PrivateEnvelopeCandidate { + /// Bounds before copying and verifies the exact one-recipient outer. + /// The reported key must still be derived and used to verify actual inner + /// containment by the qualified store; this constructor grants no authority. + pub fn from_obtained( + recipient: PublicKey, + raw: &str, + wrapping_key: &[u8; 32], + ) -> Result<Self, OperationError> { + let carrier = outer(raw, recipient)?; + Ok(Self { + recipient, + event: EnvelopeEventId::from_bytes(*carrier.envelope().id().as_bytes()), + author: *carrier.envelope().author(), + created_at: UnixSeconds::new(carrier.envelope().created_at_u64()) + .map_err(|_| OperationError::InvalidEvidence)?, + digest: Sha256::digest(raw.as_bytes()).into(), + raw: Zeroizing::new(String::from(raw)), + key: Zeroizing::new(*wrapping_key), + }) + } + /// Exact declared recipient authenticated by the outer's single p tag. + pub const fn recipient(&self) -> PublicKey { + self.recipient + } + /// Actual signed outer event identity, separate from the original seal. + pub const fn event_id(&self) -> EnvelopeEventId { + self.event + } + /// Actual outer author; the store must prove the temporary key matches. + pub const fn author(&self) -> PublicKey { + self.author + } + /// Signed randomized time, without a grant or trusted observation. + pub const fn created_at(&self) -> UnixSeconds { + self.created_at + } + /// SHA-256 of the exact original outer representation. + pub const fn digest(&self) -> &[u8; 32] { + &self.digest + } + /// Exact obtained bytes for protected handling, never diagnostic output. + pub fn raw_json(&self) -> &str { + &self.raw + } + /// Scoped borrow solely for qualified containment verification. + pub fn with_wrapping_key<T>(&self, verify: impl FnOnce(&[u8; 32]) -> T) -> T { + verify(&self.key) + } + /// Explicit bounded owner copy; retain the original until actual storage + /// completion is reconciled. This creates no persistence or dispatch fact. + pub fn retained_copy(&self) -> Self { + Self { + recipient: self.recipient, + event: self.event, + author: self.author, + created_at: self.created_at, + digest: self.digest, + raw: Zeroizing::new(String::from(self.raw_json())), + key: Zeroizing::new(*self.key), + } + } +} +impl fmt::Debug for PrivateEnvelopeCandidate { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("PrivateEnvelopeCandidate(<redacted>)") + } +}