lib

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

mod.rs (22241B)


      1 //! Authenticated browser local outboxes, independent of participant signing.
      2 //! Creation establishes a fresh unrelated buyer or explicitly selected seller outbox. Existing state
      3 //! requires its independently retained selection and protected proof.
      4 mod address;
      5 mod crypto;
      6 mod delivery;
      7 mod installation;
      8 mod issuance;
      9 mod journal;
     10 mod lease;
     11 mod listing;
     12 mod listing_installation;
     13 mod plans;
     14 mod ports;
     15 mod recovery;
     16 mod retained;
     17 
     18 use super::{Batch, Database, Error, Mutation, Namespace, OpenMode, RecordKey};
     19 use futures::{channel::oneshot, lock::Mutex};
     20 use radroots_domain::{ExecutorId, GrantId, UnixSeconds, WorkspaceId};
     21 use radroots_secrets::{
     22     SecretRef,
     23     provider::{AccessPolicy, ResidencySupport, SecretProvider, SelectionPolicy},
     24 };
     25 pub use radroots_storage::workspace::local_outbox::LocalOutboxConfig;
     26 use radroots_storage::{
     27     event::SourceGeneration,
     28     workspace::{
     29         AttachmentInput, AttachmentProof, WorkspaceBinding, WorkspaceClock, WorkspaceError,
     30         WorkspaceStore, grant::WorkspaceGrant,
     31     },
     32 };
     33 use radroots_transport::BoxFuture;
     34 use sha2::{Digest, Sha256};
     35 use std::{
     36     cell::{Cell, RefCell},
     37     fmt,
     38     future::{Future, poll_fn},
     39     rc::{Rc, Weak},
     40     task::{Poll, Waker},
     41 };
     42 use wasm_bindgen_futures::spawn_local;
     43 
     44 const JOB_BYTES: usize = 4 * 1024 * 1024;
     45 const LIVE_BYTES: usize = 4 * 1024 * 1024;
     46 const JOBS: usize = LIVE_BYTES / JOB_BYTES;
     47 const SETUPS_MAX: usize = 8;
     48 const WAITERS: usize = 32;
     49 type Signal = RefCell<Option<Waker>>;
     50 thread_local! { static SETUPS: Cell<usize> = const { Cell::new(0) }; }
     51 struct Setup;
     52 impl Setup {
     53     fn admit() -> Result<Self, WorkspaceError> {
     54         SETUPS.with(|count| {
     55             if count.get() >= SETUPS_MAX {
     56                 return Err(WorkspaceError::Capacity);
     57             }
     58             count.set(count.get() + 1);
     59             Ok(Self)
     60         })
     61     }
     62 }
     63 impl Drop for Setup {
     64     fn drop(&mut self) {
     65         SETUPS.with(|count| count.set(count.get() - 1));
     66     }
     67 }
     68 fn stored(error: Error) -> WorkspaceError {
     69     match error {
     70         Error::Closed => WorkspaceError::Closed,
     71         Error::Capacity => WorkspaceError::Capacity,
     72         Error::CommitUnknown => WorkspaceError::CommitUnknown,
     73         Error::MissingNamespace | Error::NamespaceExists => WorkspaceError::NamespaceUnavailable,
     74         _ => WorkspaceError::RecoveryRequired,
     75     }
     76 }
     77 fn namespace(input: &AttachmentInput) -> Result<Namespace, WorkspaceError> {
     78     let mut digest = Sha256::new();
     79     digest.update(b"radroots.browser.local_outbox.namespace.v2\0");
     80     digest.update(input.workspace_id().as_bytes());
     81     SourceGeneration::new(digest.finalize().into())
     82         .map(Namespace::new)
     83         .map_err(|_| WorkspaceError::InvalidInput)
     84 }
     85 fn grant_key() -> RecordKey {
     86     RecordKey::new(Sha256::digest(b"radroots.browser.local_outbox.grant.v1\0").into())
     87 }
     88 async fn commit_current(
     89     db: &Database,
     90     batch: Batch,
     91     clock: Rc<dyn WorkspaceClock>,
     92     observed: UnixSeconds,
     93     expires: UnixSeconds,
     94     active: Rc<Cell<bool>>,
     95 ) -> Result<(), WorkspaceError> {
     96     let failure = Rc::new(Cell::new(None));
     97     let guard_failure = failure.clone();
     98     let result = db
     99         .compare_exchange_checked(batch, move || {
    100             let eligible = (|| {
    101                 if !active.get() {
    102                     return Err(WorkspaceError::Closed);
    103                 }
    104                 let now = clock.now()?;
    105                 if now.get() == 0 || now < observed {
    106                     return Err(WorkspaceError::Unavailable);
    107                 }
    108                 if now >= expires {
    109                     return Err(WorkspaceError::GrantExpired);
    110                 }
    111                 Ok(())
    112             })();
    113             if let Err(error) = eligible {
    114                 guard_failure.set(Some(error));
    115                 false
    116             } else {
    117                 true
    118             }
    119         })
    120         .await;
    121     // Only a confirmed abort makes the callback refusal a known failure.
    122     // A host that completed despite refusal must retain CommitUnknown.
    123     if matches!(result, Err(Error::GuardRefused)) {
    124         return Err(failure.get().unwrap_or(WorkspaceError::RecoveryRequired));
    125     }
    126     result.map(|_| ()).map_err(stored)
    127 }
    128 fn select(
    129     provider: &dyn SecretProvider,
    130     reference: &SecretRef,
    131     policy: AccessPolicy,
    132 ) -> Result<(), WorkspaceError> {
    133     if provider.capabilities().residency() == ResidencySupport::Volatile {
    134         return Err(WorkspaceError::Unavailable);
    135     }
    136     SelectionPolicy::new(reference.backend(), policy)
    137         .select(&[provider])
    138         .map_err(|_| WorkspaceError::Unavailable)?;
    139     Ok(())
    140 }
    141 #[derive(Clone, Copy, Eq, PartialEq)]
    142 enum AccessMode {
    143     Current,
    144     CaptureOnly,
    145 }
    146 struct State {
    147     // Database drops before the lease if an unobserved owner is discarded.
    148     db: RefCell<Database>,
    149     provider: Rc<dyn SecretProvider>,
    150     reference: SecretRef,
    151     selected: AttachmentInput,
    152     clock: Rc<dyn WorkspaceClock>,
    153     mode: AccessMode,
    154     lease: RefCell<Option<lease::Lease>>,
    155     serial: Mutex<()>,
    156     jobs: Cell<usize>,
    157     uncertain: Cell<bool>,
    158     capture_scope: RefCell<Option<recovery::CaptureIdentity>>,
    159     recovery: RefCell<Option<recovery::Authorization>>,
    160     closing: Cell<bool>,
    161     closed: Cell<Option<Result<(), WorkspaceError>>>,
    162     drain: RefCell<Option<Waker>>,
    163     waiters: RefCell<Vec<Weak<Signal>>>,
    164 }
    165 impl State {
    166     fn database(&self) -> Database {
    167         self.db.borrow().clone()
    168     }
    169     fn mark_unknown(&self) {
    170         self.uncertain.set(true);
    171     }
    172     fn mark_capture_unknown(&self, identity: recovery::CaptureIdentity) {
    173         if !self.uncertain.replace(true) {
    174             *self.capture_scope.borrow_mut() = Some(identity);
    175         } else if self.capture_scope.borrow().as_ref() != Some(&identity) {
    176             self.capture_scope.borrow_mut().take();
    177         }
    178     }
    179     fn active(&self) -> Result<Rc<Cell<bool>>, WorkspaceError> {
    180         let active = self
    181             .lease
    182             .borrow()
    183             .as_ref()
    184             .map(lease::Lease::active)
    185             .ok_or(WorkspaceError::Closed)?;
    186         if !active.get() {
    187             return Err(WorkspaceError::Closed);
    188         }
    189         Ok(active)
    190     }
    191     fn admit(self: &Rc<Self>) -> Result<Work, WorkspaceError> {
    192         self.admit_mode(false)
    193     }
    194     fn admit_capture(self: &Rc<Self>) -> Result<Work, WorkspaceError> {
    195         self.admit_mode(true)
    196     }
    197     fn admit_mode(self: &Rc<Self>, capture: bool) -> Result<Work, WorkspaceError> {
    198         if self.closing.get() || (self.uncertain.get() && !capture) {
    199             return Err(WorkspaceError::Closed);
    200         }
    201         if self.active().is_err() {
    202             self.stop();
    203             return Err(WorkspaceError::Closed);
    204         }
    205         if self.jobs.get() >= JOBS {
    206             return Err(WorkspaceError::Capacity);
    207         }
    208         self.jobs.set(self.jobs.get() + 1);
    209         Ok(Work(self.clone(), self.uncertain.get()))
    210     }
    211     fn stop(self: &Rc<Self>) {
    212         if self.closing.replace(true) {
    213             return;
    214         }
    215         let state = self.clone();
    216         spawn_local(async move {
    217             poll_fn(|cx| {
    218                 if state.jobs.get() == 0 {
    219                     Poll::Ready(())
    220                 } else {
    221                     *state.drain.borrow_mut() = Some(cx.waker().clone());
    222                     Poll::Pending
    223                 }
    224             })
    225             .await;
    226             let database = state.database().close().await.map_err(stored);
    227             let lease = state.lease.borrow_mut().take();
    228             let released = match lease {
    229                 Some(lease) => lease.release().await,
    230                 None => Err(WorkspaceError::RecoveryRequired),
    231             };
    232             state.closed.set(Some(database.and(released)));
    233             state.waiters.borrow_mut().retain(|weak| {
    234                 if let Some(signal) = weak.upgrade() {
    235                     if let Some(waker) = signal.borrow_mut().take() {
    236                         waker.wake();
    237                     }
    238                     true
    239                 } else {
    240                     false
    241                 }
    242             });
    243         });
    244     }
    245     async fn access(
    246         &self,
    247         input: &AttachmentInput,
    248         proof: &AttachmentProof,
    249     ) -> Result<(WorkspaceGrant, Vec<u8>, WorkspaceBinding), WorkspaceError> {
    250         if self.mode != AccessMode::Current {
    251             return Err(WorkspaceError::Unauthorized);
    252         }
    253         let (record, protected) = self.capture_grant(input, proof).await?;
    254         let binding = record.authenticate(input, proof, self.clock.now()?)?;
    255         self.active()?;
    256         Ok((record, protected, binding))
    257     }
    258     async fn capture_grant(
    259         &self,
    260         input: &AttachmentInput,
    261         proof: &AttachmentProof,
    262     ) -> Result<(WorkspaceGrant, Vec<u8>), WorkspaceError> {
    263         self.active()?;
    264         if input != &self.selected {
    265             return Err(WorkspaceError::Unauthorized);
    266         }
    267         let protected = self
    268             .database()
    269             .get(grant_key())
    270             .await
    271             .map_err(stored)?
    272             .ok_or(WorkspaceError::RecoveryRequired)?;
    273         let plaintext = crypto::open(
    274             self.provider.as_ref(),
    275             &self.reference,
    276             self.selected.workspace_id(),
    277             self.selected.grant_id(),
    278             &protected,
    279         )
    280         .await?;
    281         let record = plaintext.expose_secret(WorkspaceGrant::decode_outbox)?;
    282         record.authenticate_retained_capture(input, proof)?;
    283         self.active()?;
    284         Ok((record, protected))
    285     }
    286 }
    287 struct Work(Rc<State>, bool);
    288 impl Drop for Work {
    289     fn drop(&mut self) {
    290         self.0.jobs.set(self.0.jobs.get() - 1);
    291         if self.0.jobs.get() == 0
    292             && let Some(waker) = self.0.drain.borrow_mut().take()
    293         {
    294             waker.wake();
    295         }
    296     }
    297 }
    298 trait JobError: From<WorkspaceError> {
    299     fn workspace_failure(&self) -> Option<WorkspaceError>;
    300 }
    301 impl JobError for WorkspaceError {
    302     fn workspace_failure(&self) -> Option<WorkspaceError> {
    303         Some(*self)
    304     }
    305 }
    306 impl JobError for radroots_storage::command::OperationError {
    307     fn workspace_failure(&self) -> Option<WorkspaceError> {
    308         match self {
    309             Self::Workspace(error) => Some(*error),
    310             Self::RecoveryRequired => Some(WorkspaceError::RecoveryRequired),
    311             _ => None,
    312         }
    313     }
    314 }
    315 async fn owned<T: 'static, E: JobError + 'static>(
    316     work: Work,
    317     future: impl Future<Output = Result<T, E>> + 'static,
    318 ) -> Result<T, E> {
    319     let (send, observe) = oneshot::channel();
    320     spawn_local(async move {
    321         let state = work.0.clone();
    322         let recovery = work.1;
    323         let _work = work;
    324         let _serial = state.serial.lock().await;
    325         let result = future.await;
    326         let failure = result.as_ref().err().and_then(JobError::workspace_failure);
    327         if failure == Some(WorkspaceError::CommitUnknown) {
    328             state.mark_unknown();
    329         } else if matches!(
    330             failure,
    331             Some(
    332                 WorkspaceError::Closed
    333                     | WorkspaceError::Unavailable
    334                     | WorkspaceError::RecoveryRequired
    335             )
    336         ) && (!recovery || state.active().is_err())
    337         {
    338             state.stop();
    339         }
    340         let _ = send.send(result);
    341     });
    342     observe
    343         .await
    344         .unwrap_or_else(|_| Err(WorkspaceError::CommitUnknown.into()))
    345 }
    346 /// One bounded browser writer. Clones share admission, serial work and actual
    347 /// close completion. No proof or participant signer is retained in the handle.
    348 #[derive(Clone)]
    349 pub struct BrowserWorkspace {
    350     state: Rc<State>,
    351 }
    352 impl BrowserWorkspace {
    353     /// Enrolls only a new unrelated buyer or seller outbox and returns its independently
    354     /// retained selection/proof after the protected grant actually commits.
    355     pub async fn initialize_local_outbox(
    356         config: LocalOutboxConfig,
    357         provider: Rc<dyn SecretProvider>,
    358         reference: SecretRef,
    359         policy: AccessPolicy,
    360         clock: Rc<dyn WorkspaceClock>,
    361     ) -> Result<(Self, AttachmentInput, AttachmentProof), WorkspaceError> {
    362         select(provider.as_ref(), &reference, policy)?;
    363         let setup = Setup::admit()?;
    364         let now = clock.now()?;
    365         config.validate_at(now)?;
    366         let workspace = WorkspaceId::from_bytes(*crypto::random::<32>()?);
    367         let executor = ExecutorId::from_bytes(*crypto::random::<32>()?);
    368         let grant = GrantId::from_bytes(*crypto::random::<32>()?);
    369         let secret = crypto::random::<32>()?;
    370         let proof = AttachmentProof::from_protected_input(secret.as_ref())?;
    371         let (input, proof, record) = config.enroll(now, workspace, executor, grant, proof)?;
    372         let (send, observe) = oneshot::channel();
    373         spawn_local(async move {
    374             let _setup = setup;
    375             let result = async {
    376                 let selected = namespace(&input)?;
    377                 let lease = lease::Lease::acquire(&selected.name()).await?;
    378                 let db = match Database::open(selected, OpenMode::CreateNew).await {
    379                     Ok(db) => db,
    380                     Err(error) => {
    381                         lease.release().await?;
    382                         return Err(stored(error));
    383                     }
    384                 };
    385                 let owner = Self::assemble(
    386                     db,
    387                     provider,
    388                     reference,
    389                     input.clone(),
    390                     clock,
    391                     lease,
    392                     AccessMode::Current,
    393                 );
    394                 let initialized = async {
    395                     let bytes = record.encode()?;
    396                     let binding = record.authenticate(&input, &proof, now)?;
    397                     let protected = crypto::seal(
    398                         owner.state.provider.as_ref(),
    399                         &owner.state.reference,
    400                         workspace,
    401                         grant,
    402                         &bytes,
    403                     )
    404                     .await?;
    405                     let batch = Batch::new(vec![
    406                         Mutation::new(grant_key(), None, Some(protected)).map_err(stored)?,
    407                     ])
    408                     .map_err(stored)?;
    409                     commit_current(
    410                         &owner.state.database(),
    411                         batch,
    412                         owner.state.clock.clone(),
    413                         binding.observed_at(),
    414                         binding.expires_at(),
    415                         owner.state.active()?,
    416                     )
    417                     .await?;
    418                     record.authenticate(&input, &proof, owner.state.clock.now()?)?;
    419                     Ok::<(), WorkspaceError>(())
    420                 }
    421                 .await;
    422                 if let Err(error) = initialized {
    423                     owner.close().await?;
    424                     return Err(error);
    425                 }
    426                 Ok((owner, input, proof))
    427             }
    428             .await;
    429             let _ = send.send(result);
    430         });
    431         observe.await.unwrap_or(Err(WorkspaceError::CommitUnknown))
    432     }
    433     /// Opens an exact existing outbox and authenticates its retained protected
    434     /// proof. Missing records never become a newly enrolled grant.
    435     pub async fn open_existing(
    436         input: AttachmentInput,
    437         proof: AttachmentProof,
    438         provider: Rc<dyn SecretProvider>,
    439         reference: SecretRef,
    440         policy: AccessPolicy,
    441         clock: Rc<dyn WorkspaceClock>,
    442     ) -> Result<Self, WorkspaceError> {
    443         Self::open_mode(
    444             input,
    445             proof,
    446             provider,
    447             reference,
    448             policy,
    449             clock,
    450             AccessMode::Current,
    451         )
    452         .await
    453     }
    454     /// Opens only for appending matching already obtained output to an actual
    455     /// original claim. This handle cannot authenticate or admit fresh work.
    456     pub async fn open_existing_for_capture(
    457         input: AttachmentInput,
    458         proof: AttachmentProof,
    459         provider: Rc<dyn SecretProvider>,
    460         reference: SecretRef,
    461         policy: AccessPolicy,
    462         clock: Rc<dyn WorkspaceClock>,
    463     ) -> Result<Self, WorkspaceError> {
    464         Self::open_mode(
    465             input,
    466             proof,
    467             provider,
    468             reference,
    469             policy,
    470             clock,
    471             AccessMode::CaptureOnly,
    472         )
    473         .await
    474     }
    475     async fn open_mode(
    476         input: AttachmentInput,
    477         proof: AttachmentProof,
    478         provider: Rc<dyn SecretProvider>,
    479         reference: SecretRef,
    480         policy: AccessPolicy,
    481         clock: Rc<dyn WorkspaceClock>,
    482         mode: AccessMode,
    483     ) -> Result<Self, WorkspaceError> {
    484         select(provider.as_ref(), &reference, policy)?;
    485         let setup = Setup::admit()?;
    486         let (send, observe) = oneshot::channel();
    487         spawn_local(async move {
    488             let _setup = setup;
    489             let result = async {
    490                 let selected = namespace(&input)?;
    491                 let lease = lease::Lease::acquire(&selected.name()).await?;
    492                 let db = match Database::open(selected, OpenMode::Existing).await {
    493                     Ok(db) => db,
    494                     Err(error) => {
    495                         lease.release().await?;
    496                         return Err(stored(error));
    497                     }
    498                 };
    499                 let owner =
    500                     Self::assemble(db, provider, reference, input.clone(), clock, lease, mode);
    501                 let authenticated = match mode {
    502                     AccessMode::Current => owner.state.access(&input, &proof).await.map(|_| ()),
    503                     AccessMode::CaptureOnly => {
    504                         owner.state.capture_grant(&input, &proof).await.map(|_| ())
    505                     }
    506                 };
    507                 if let Err(error) = authenticated {
    508                     owner.close().await?;
    509                     return Err(error);
    510                 }
    511                 Ok(owner)
    512             }
    513             .await;
    514             let _ = send.send(result);
    515         });
    516         observe.await.unwrap_or(Err(WorkspaceError::CommitUnknown))
    517     }
    518     fn assemble(
    519         db: Database,
    520         provider: Rc<dyn SecretProvider>,
    521         reference: SecretRef,
    522         selected: AttachmentInput,
    523         clock: Rc<dyn WorkspaceClock>,
    524         lease: lease::Lease,
    525         mode: AccessMode,
    526     ) -> Self {
    527         Self {
    528             state: Rc::new(State {
    529                 db: RefCell::new(db),
    530                 provider,
    531                 reference,
    532                 selected,
    533                 clock,
    534                 mode,
    535                 lease: RefCell::new(Some(lease)),
    536                 serial: Mutex::new(()),
    537                 jobs: Cell::new(0),
    538                 uncertain: Cell::new(false),
    539                 capture_scope: RefCell::new(None),
    540                 recovery: RefCell::new(None),
    541                 closing: Cell::new(false),
    542                 closed: Cell::new(None),
    543                 drain: RefCell::new(None),
    544                 waiters: RefCell::new(Vec::new()),
    545             }),
    546         }
    547     }
    548     /// Authenticates and atomically revokes the current protected grant.
    549     pub async fn revoke(
    550         &self,
    551         input: AttachmentInput,
    552         proof: AttachmentProof,
    553     ) -> Result<(), WorkspaceError> {
    554         let work = self.state.admit()?;
    555         let state = self.state.clone();
    556         owned(work, async move {
    557             let (mut record, expected, current) = state.access(&input, &proof).await?;
    558             record.revoke()?;
    559             let bytes = record.encode()?;
    560             let protected = crypto::seal(
    561                 state.provider.as_ref(),
    562                 &state.reference,
    563                 input.workspace_id(),
    564                 input.grant_id(),
    565                 &bytes,
    566             )
    567             .await?;
    568             // A foreign writer cannot substitute the grant across async crypto.
    569             let batch = Batch::new(vec![
    570                 Mutation::new(grant_key(), Some(expected), Some(protected)).map_err(stored)?,
    571             ])
    572             .map_err(stored)?;
    573             commit_current(
    574                 &state.database(),
    575                 batch,
    576                 state.clock.clone(),
    577                 current.observed_at(),
    578                 current.expires_at(),
    579                 state.active()?,
    580             )
    581             .await?;
    582             Ok(())
    583         })
    584         .await
    585     }
    586     /// Stops admission and observes drained database closure and Web Lock release.
    587     /// Dropping this observation does not cancel the Rust-owned close operation.
    588     pub async fn close(&self) -> Result<(), WorkspaceError> {
    589         self.state.stop();
    590         if let Some(result) = self.state.closed.get() {
    591             return result;
    592         }
    593         let signal = Rc::new(RefCell::new(None));
    594         {
    595             let mut waiters = self.state.waiters.borrow_mut();
    596             waiters.retain(|weak| weak.strong_count() > 0);
    597             if waiters.len() >= WAITERS {
    598                 return Err(WorkspaceError::Capacity);
    599             }
    600             waiters.push(Rc::downgrade(&signal));
    601         }
    602         poll_fn(|cx| {
    603             if let Some(result) = self.state.closed.get() {
    604                 Poll::Ready(result)
    605             } else {
    606                 *signal.borrow_mut() = Some(cx.waker().clone());
    607                 Poll::Pending
    608             }
    609         })
    610         .await
    611     }
    612 }
    613 impl fmt::Debug for BrowserWorkspace {
    614     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    615         f.write_str("BrowserWorkspace(<redacted>)")
    616     }
    617 }
    618 impl WorkspaceStore for BrowserWorkspace {
    619     fn authenticate(
    620         &self,
    621         input: AttachmentInput,
    622         proof: AttachmentProof,
    623     ) -> BoxFuture<'_, Result<WorkspaceBinding, WorkspaceError>> {
    624         Box::pin(async move {
    625             let work = self.state.admit()?;
    626             let state = self.state.clone();
    627             owned(work, async move {
    628                 state
    629                     .access(&input, &proof)
    630                     .await
    631                     .map(|(_, _, binding)| binding)
    632             })
    633             .await
    634         })
    635     }
    636     fn close_workspace(&self) -> BoxFuture<'_, Result<(), WorkspaceError>> {
    637         Box::pin(self.close())
    638     }
    639 }