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 }