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:
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>)")
+ }
+}