lib

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

envelope.rs (8147B)


      1 //! Original stock-envelope selectors and non-authoritative retained reports.
      2 use super::*;
      3 use core::{fmt, num::NonZeroU64};
      4 use radroots_domain::{EnvelopeEventId, PublicKey};
      5 use sha2::{Digest, Sha256};
      6 use zeroize::Zeroizing;
      7 
      8 /// Original recipient selectors and nullable observation; never stock authority.
      9 pub struct StockEnvelopeRequest {
     10     binding: WorkspaceBinding,
     11     minimum: InventoryCheckpointRef,
     12     operation: OperationId,
     13     digest: CommandDigest,
     14     recipient: PublicKey,
     15     observed: Option<NonZeroU64>,
     16     envelope: Option<EnvelopeEventId>,
     17 }
     18 impl StockEnvelopeRequest {
     19     pub fn new(
     20         binding: WorkspaceBinding,
     21         minimum: InventoryCheckpointRef,
     22         operation: OperationId,
     23         digest: CommandDigest,
     24         recipient: PublicKey,
     25         observed: Option<NonZeroU64>,
     26     ) -> Result<Self, OperationError> {
     27         if binding.scope() != WorkspaceScope::SellerStockOwner {
     28             return Err(OperationError::Unauthorized);
     29         }
     30         if minimum.authority() != binding.input().authority() {
     31             return Err(crate::workspace::WorkspaceError::StaleAuthority.into());
     32         }
     33         Ok(Self {
     34             binding,
     35             minimum,
     36             operation,
     37             digest,
     38             recipient,
     39             observed,
     40             envelope: None,
     41         })
     42     }
     43     /// Selects an exact retained outer. This metadata grants neither wrapping
     44     /// nor transport permission. Omission keeps original-envelope semantics.
     45     pub const fn with_envelope(mut self, event: EnvelopeEventId) -> Self {
     46         self.envelope = Some(event);
     47         self
     48     }
     49     pub const fn envelope_event_id(&self) -> Option<EnvelopeEventId> {
     50         self.envelope
     51     }
     52     pub const fn binding(&self) -> &WorkspaceBinding {
     53         &self.binding
     54     }
     55     pub const fn minimum_checkpoint(&self) -> InventoryCheckpointRef {
     56         self.minimum
     57     }
     58     pub const fn operation_id(&self) -> OperationId {
     59         self.operation
     60     }
     61     pub const fn command_digest(&self) -> CommandDigest {
     62         self.digest
     63     }
     64     pub const fn recipient(&self) -> PublicKey {
     65         self.recipient
     66     }
     67     pub const fn observed_at_unix_ms(&self) -> Option<NonZeroU64> {
     68         self.observed
     69     }
     70     pub fn attempt(&self) -> CommitAttempt {
     71         CommitAttempt::new(
     72             self.binding.input().workspace_id(),
     73             self.operation,
     74             self.digest,
     75             None,
     76         )
     77     }
     78 }
     79 impl fmt::Debug for StockEnvelopeRequest {
     80     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
     81         f.write_str("StockEnvelopeRequest(<redacted>)")
     82     }
     83 }
     84 
     85 /// Actual capture metadata, independent of grant, dispatch or relay acceptance.
     86 #[derive(Clone, Copy, Eq, PartialEq)]
     87 pub struct StockEnvelopeReceipt {
     88     attempt: CommitAttempt,
     89     evidence: StockEvidenceReceipt,
     90     installation: TransactionId,
     91     event: EnvelopeEventId,
     92     digest: [u8; 32],
     93     checkpoint: InventoryCheckpointRef,
     94     observed: Option<NonZeroU64>,
     95     rewrap_admission: Option<TransactionId>,
     96 }
     97 impl StockEnvelopeReceipt {
     98     /// Checks scoped report shape only. The concrete host must authenticate
     99     /// actual original S/T2, containment and confirmed capture atomically.
    100     pub fn from_committed_store(
    101         request: &StockEnvelopeRequest,
    102         attempt: CommitAttempt,
    103         evidence: StockEvidenceReceipt,
    104         installation: TransactionId,
    105         event: EnvelopeEventId,
    106         digest: [u8; 32],
    107         checkpoint: InventoryCheckpointRef,
    108     ) -> Result<Self, OperationError> {
    109         let source = evidence.attempt();
    110         if attempt.transaction_id().is_none()
    111             || attempt.workspace_id() != request.binding().input().workspace_id()
    112             || attempt.operation_id() != request.operation_id()
    113             || attempt.command_digest() != request.command_digest()
    114             || source.workspace_id() != attempt.workspace_id()
    115             || source.operation_id() != attempt.operation_id()
    116             || source.command_digest() != attempt.command_digest()
    117             || evidence.recipient() != request.recipient()
    118             || checkpoint.authority() != request.binding().input().authority()
    119             || checkpoint.revision().get() == 0
    120             || request
    121                 .envelope_event_id()
    122                 .is_some_and(|selected| selected != event)
    123         {
    124             return Err(OperationError::RecoveryRequired);
    125         }
    126         Ok(Self {
    127             attempt,
    128             evidence,
    129             installation,
    130             event,
    131             digest,
    132             checkpoint,
    133             observed: request.observed_at_unix_ms(),
    134             rewrap_admission: None,
    135         })
    136     }
    137     pub const fn attempt(&self) -> CommitAttempt {
    138         self.attempt
    139     }
    140     pub const fn evidence(&self) -> StockEvidenceReceipt {
    141         self.evidence
    142     }
    143     pub const fn recipient(&self) -> PublicKey {
    144         self.evidence.recipient()
    145     }
    146     pub const fn installation_transaction_id(&self) -> TransactionId {
    147         self.installation
    148     }
    149     pub const fn event_id(&self) -> EnvelopeEventId {
    150         self.event
    151     }
    152     pub const fn digest(&self) -> &[u8; 32] {
    153         &self.digest
    154     }
    155     pub const fn checkpoint(&self) -> InventoryCheckpointRef {
    156         self.checkpoint
    157     }
    158     pub const fn observed_at_unix_ms(&self) -> Option<NonZeroU64> {
    159         self.observed
    160     }
    161     pub const fn rewrap_admission_transaction_id(&self) -> Option<TransactionId> {
    162         self.rewrap_admission
    163     }
    164     /// Links a reported additional outer to its original wrapping admission.
    165     /// Only shape is checked; the qualified host authenticates actual F13/F14.
    166     pub fn with_rewrap_admission(
    167         mut self,
    168         admission: &super::StockRewrapAdmission,
    169     ) -> Result<Self, OperationError> {
    170         let original = admission.original();
    171         if self.evidence != original.evidence()
    172             || self.installation != original.installation_transaction_id()
    173             || self.event == original.event_id()
    174             || self.checkpoint.authority() != admission.checkpoint().authority()
    175             || self.checkpoint.revision() <= admission.checkpoint().revision()
    176             || self.attempt.transaction_id() == Some(admission.transaction_id())
    177             || self
    178                 .rewrap_admission
    179                 .is_some_and(|transaction| transaction != admission.transaction_id())
    180         {
    181             return Err(OperationError::RecoveryRequired);
    182         }
    183         self.rewrap_admission = Some(admission.transaction_id());
    184         Ok(self)
    185     }
    186 }
    187 impl fmt::Debug for StockEnvelopeReceipt {
    188     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    189         f.write_str("StockEnvelopeReceipt(<redacted>)")
    190     }
    191 }
    192 
    193 /// Exact retained outer. Construction verifies its carrier and reported digest,
    194 /// but grants no backend, inventory, dispatch or relay-acceptance authority.
    195 pub struct StockEnvelopeSource {
    196     receipt: StockEnvelopeReceipt,
    197     raw: Zeroizing<String>,
    198 }
    199 impl StockEnvelopeSource {
    200     pub fn from_retained_wire(
    201         receipt: StockEnvelopeReceipt,
    202         raw: &str,
    203     ) -> Result<Self, OperationError> {
    204         let outer = crate::command::verified_private_outer(raw, receipt.recipient())?;
    205         if outer.envelope().id().as_bytes() != receipt.event_id().as_bytes()
    206             || <[u8; 32]>::from(Sha256::digest(raw.as_bytes())) != *receipt.digest()
    207         {
    208             return Err(OperationError::InvalidEvidence);
    209         }
    210         Ok(Self {
    211             receipt,
    212             raw: Zeroizing::new(raw.to_owned()),
    213         })
    214     }
    215     pub const fn receipt(&self) -> StockEnvelopeReceipt {
    216         self.receipt
    217     }
    218     pub fn with_json<T>(&self, use_json: impl FnOnce(&str) -> T) -> T {
    219         use_json(&self.raw)
    220     }
    221 }
    222 impl fmt::Debug for StockEnvelopeSource {
    223     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    224         f.write_str("StockEnvelopeSource(<redacted>)")
    225     }
    226 }
    227 
    228 /// Confirmed original capture or its actual unresolved transaction identity.
    229 #[derive(Debug)]
    230 pub enum StockEnvelopeOutcome {
    231     Committed(Box<StockEnvelopeReceipt>),
    232     Unknown(CommitAttempt),
    233 }