Skip to main content

qualia_core_db/sensing/local_custody/
local_recovery.rs

1//! Inspect a checkpoint using the signed head of a held local lease.
2//!
3//! The host must maintain root protection, locality, rollback-resistant
4//! freshness and a read/policy lease through return. A file lock and two equal
5//! snapshots do not independently prove those properties.
6use super::{
7    chain::{ChainAuthorityError, ChainHead},
8    local_head::{LocalHeadError, LocalHeadLease, LocalHeadPolicy},
9    recovery::{
10        inspect_recovery_bundle, MembershipAssertion, RecoveryAuthority, RecoveryError,
11        RecoveryReport,
12    },
13    CustodyAuthority, SidecarReceipt, SidecarReceiptAuthority, SIDECAR_BYTES,
14};
15use std::path::Path;
16
17/// Current exact recovery permission and authenticated membership evidence.
18/// Missing ancestry/exclusion evidence must return `Unknown`. Implementations
19/// must bind their proof to the root, chain, receipt and supplied head.
20pub trait LocalRecoveryPolicy: LocalHeadPolicy + CustodyAuthority {
21    fn permit_recovery_read(
22        &mut self,
23        root: &Path,
24        chain: &[u8; 32],
25        checkpoint: &[u8; 32],
26        byte_budget: usize,
27    ) -> bool;
28
29    fn verify_recovery_membership(
30        &mut self,
31        root: &Path,
32        chain: &[u8; 32],
33        head: ChainHead,
34        receipt: &SidecarReceipt,
35    ) -> Result<MembershipAssertion, ChainAuthorityError>;
36}
37
38/// Use one caller-held lease without opening another head or acquiring another
39/// lock. No writes, head changes, scans, repair or deletion are performed.
40/// The checkpoint bytes and head are verified through existing custody APIs;
41/// the policy supplies authenticated membership and anti-rollback authority.
42#[allow(clippy::too_many_arguments)]
43pub fn inspect_local_recovery<P: LocalRecoveryPolicy>(
44    root: &Path,
45    chain: &[u8; 32],
46    checkpoint: &[u8; 32],
47    byte_budget: usize,
48    sidecar: &mut [u8; SIDECAR_BYTES],
49    payload: &mut [u8],
50    lease: &mut LocalHeadLease<'_>,
51    policy: &mut P,
52) -> Result<RecoveryReport, RecoveryError> {
53    sidecar.fill(0);
54    payload.fill(0);
55    if !lease.matches_scope(root, chain) {
56        return Err(RecoveryError::Authority(ChainAuthorityError::NotAuthorized));
57    }
58    let mut authority = BoundLocalRecovery {
59        lease,
60        policy,
61        root,
62        chain,
63        checkpoint,
64        byte_budget,
65    };
66    inspect_recovery_bundle(
67        root,
68        chain,
69        checkpoint,
70        byte_budget,
71        sidecar,
72        payload,
73        &mut authority,
74    )
75}
76
77struct BoundLocalRecovery<'lease, 'key, 'scope, P> {
78    lease: &'lease mut LocalHeadLease<'key>,
79    policy: &'lease mut P,
80    root: &'scope Path,
81    chain: &'scope [u8; 32],
82    checkpoint: &'scope [u8; 32],
83    byte_budget: usize,
84}
85
86impl<P: LocalRecoveryPolicy> BoundLocalRecovery<'_, '_, '_, P> {
87    fn exact(&self, root: &Path, chain: &[u8; 32], checkpoint: &[u8; 32], budget: usize) -> bool {
88        root == self.root
89            && chain == self.chain
90            && checkpoint == self.checkpoint
91            && budget == self.byte_budget
92            && self.lease.matches_scope(root, chain)
93    }
94
95    fn authorize_head_read(&mut self, root: &Path, chain: &[u8; 32]) -> bool {
96        self.exact(root, chain, self.checkpoint, self.byte_budget)
97            && self
98                .policy
99                .permit_recovery_read(root, chain, self.checkpoint, self.byte_budget)
100            && self
101                .policy
102                .permit_read(root, self.checkpoint, self.byte_budget)
103    }
104}
105
106impl<P: LocalRecoveryPolicy> SidecarReceiptAuthority for BoundLocalRecovery<'_, '_, '_, P> {
107    fn permits(
108        &self,
109        receipt: &SidecarReceipt,
110        sidecar: &[u8; SIDECAR_BYTES],
111        payload: &[u8],
112    ) -> bool {
113        receipt.chain_id() == self.chain
114            && &receipt.checkpoint() == self.checkpoint
115            && self.policy.permits(receipt, sidecar, payload)
116    }
117}
118
119impl<P: LocalRecoveryPolicy> CustodyAuthority for BoundLocalRecovery<'_, '_, '_, P> {
120    fn permit_publish(
121        &mut self,
122        _: &Path,
123        _: &SidecarReceipt,
124        _: &[u8; SIDECAR_BYTES],
125        _: &[u8],
126        _: usize,
127    ) -> bool {
128        false
129    }
130
131    fn permit_read(&mut self, root: &Path, checkpoint: &[u8; 32], byte_budget: usize) -> bool {
132        self.exact(root, self.chain, checkpoint, byte_budget)
133            && self.policy.permit_read(root, checkpoint, byte_budget)
134    }
135}
136
137impl<P: LocalRecoveryPolicy> RecoveryAuthority for BoundLocalRecovery<'_, '_, '_, P> {
138    fn permit_recovery(
139        &mut self,
140        root: &Path,
141        chain: &[u8; 32],
142        checkpoint: &[u8; 32],
143        byte_budget: usize,
144    ) -> bool {
145        self.exact(root, chain, checkpoint, byte_budget)
146            && self
147                .policy
148                .permit_recovery_read(root, chain, checkpoint, byte_budget)
149    }
150
151    fn recovery_head(
152        &mut self,
153        root: &Path,
154        chain: &[u8; 32],
155    ) -> Result<ChainHead, ChainAuthorityError> {
156        if !self.authorize_head_read(root, chain) {
157            return Err(ChainAuthorityError::NotAuthorized);
158        }
159        self.lease.current(self.policy).map_err(map_head_error)
160    }
161
162    fn membership(
163        &mut self,
164        root: &Path,
165        head: ChainHead,
166        receipt: &SidecarReceipt,
167    ) -> Result<MembershipAssertion, ChainAuthorityError> {
168        if receipt.chain_id() != self.chain
169            || &receipt.checkpoint() != self.checkpoint
170            || !self.authorize_head_read(root, receipt.chain_id())
171        {
172            return Err(ChainAuthorityError::NotAuthorized);
173        }
174        self.policy
175            .verify_recovery_membership(root, self.chain, head, receipt)
176    }
177}
178
179fn map_head_error(error: LocalHeadError) -> ChainAuthorityError {
180    match error {
181        LocalHeadError::PermissionDenied => ChainAuthorityError::NotAuthorized,
182        LocalHeadError::InvalidEncoding
183        | LocalHeadError::InvalidSigner
184        | LocalHeadError::InvalidSignature
185        | LocalHeadError::InvalidChain => ChainAuthorityError::InvalidState,
186        _ => ChainAuthorityError::Unavailable,
187    }
188}
189
190#[cfg(test)]
191#[path = "local_recovery_tests.rs"]
192mod tests;