lib

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

signer.rs (3929B)


      1 //! Object-safe signer service-provider interface.
      2 
      3 use core::{future::Future, pin::Pin};
      4 
      5 #[cfg(not(feature = "std"))]
      6 use alloc::boxed::Box;
      7 #[cfg(feature = "std")]
      8 use std::boxed::Box;
      9 
     10 use crate::{
     11     AuthoredSignEvidence, Error, SignReceipt, SignRequest, SignerStatus,
     12     error::Kind,
     13     host::{HostBound, Shared},
     14     receipt::verify_identity,
     15 };
     16 
     17 /// A native Send future or a browser-local signer future.
     18 #[cfg(not(target_arch = "wasm32"))]
     19 pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
     20 /// A native Send future or a browser-local signer future.
     21 #[cfg(target_arch = "wasm32")]
     22 pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;
     23 
     24 /// Protocol-neutral, caller-driven signing service-provider interface.
     25 ///
     26 /// Implementations must document their durable remote-effect point. Dropping
     27 /// a future after that point does not imply rollback. Replay behavior is
     28 /// advertised through signer status and every successful result must use a
     29 /// verified receipt or authored-evidence constructor.
     30 pub trait Signer: HostBound {
     31     fn status(&self) -> BoxFuture<'_, Result<SignerStatus, Error>>;
     32 
     33     /// Signs one already-authorized exact plan.
     34     ///
     35     /// Implementations must observe the request's millisecond deadline and
     36     /// cancellation signal throughout the operation, preserve its stable
     37     /// signer request ID for remote replay, and create success only through
     38     /// [`SignReceipt::from_signed_event`].
     39     fn sign(&self, request: SignRequest) -> BoxFuture<'_, Result<SignReceipt, Error>>;
     40 
     41     /// Signs an authored plan while retaining any verified result of started work.
     42     ///
     43     /// An override must honor deadline and cancellation before starting work,
     44     /// but may return exact evidence received afterward. Such evidence is not
     45     /// permission to resume stopped work. The composing host owns polling and
     46     /// durable reconciliation; dropping this future does not undo a signature.
     47     ///
     48     /// The default delegates to [`Self::sign`] and preserves existing adapters.
     49     /// It cannot recover evidence that the adapter discards. Blossom requests
     50     /// and already-cancelled requests are rejected before invoking that adapter.
     51     fn sign_authored_evidence(
     52         &self,
     53         request: SignRequest,
     54     ) -> BoxFuture<'_, Result<AuthoredSignEvidence, Error>> {
     55         Box::pin(async move {
     56             if request.authored_plan().is_none() {
     57                 return Err(Error::new(Kind::InvalidArgument));
     58             }
     59             if request.cancellation_signal().is_cancelled() {
     60                 return Err(Error::new(Kind::SignerCancelled));
     61             }
     62             let receipt = self.sign(request.clone()).await?;
     63             verify_identity(
     64                 receipt.operation_kind(),
     65                 receipt.intent_id(),
     66                 receipt.signer_request_id(),
     67                 &request,
     68             )?;
     69             AuthoredSignEvidence::from_signed_event(
     70                 &request,
     71                 receipt.signed_event().clone(),
     72                 receipt.completed_at_unix_ms(),
     73             )
     74         })
     75     }
     76 }
     77 
     78 /// Shared signer handle used by composing hosts without selecting a runtime.
     79 pub type DynSigner = Shared<dyn Signer>;
     80 
     81 #[cfg(test)]
     82 mod tests {
     83     use super::*;
     84 
     85     struct Stub;
     86 
     87     impl Signer for Stub {
     88         fn status(&self) -> BoxFuture<'_, Result<SignerStatus, Error>> {
     89             Box::pin(async { Ok(SignerStatus::unavailable()) })
     90         }
     91 
     92         fn sign(&self, _request: SignRequest) -> BoxFuture<'_, Result<SignReceipt, Error>> {
     93             Box::pin(async { Err(Error::new(Kind::SignerUnavailable)) })
     94         }
     95     }
     96 
     97     #[cfg(not(target_arch = "wasm32"))]
     98     #[test]
     99     fn signer_remains_dyn_send_and_sync() {
    100         fn assert_dyn(_: &dyn Signer) {}
    101         fn assert_send_sync<T: Send + Sync + ?Sized>() {}
    102         assert_dyn(&Stub);
    103         assert_send_sync::<dyn Signer>();
    104     }
    105 }