Skip to main content

qualia_core_db/sensing/
sidecar_attestation.rs

1//! Signed, caller-buffered custody receipts for experimental sensing sidecars.
2//!
3//! The signature binds exact sidecar and payload bytes; it does not validate
4//! their format, scientific truth, permission, signer authority or chain
5//! completeness. The host must decode the sidecar against a resolved payload
6//! and enforce current authority, revocation, scope, and checkpoint policy.
7//! This module performs no storage, network, or device I/O.
8
9use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
10use sha2::{Digest, Sha256};
11
12pub const SIDECAR_BYTES: usize = 768;
13pub const SIDECAR_RECEIPT_BYTES: usize = 272;
14const MAGIC: &[u8; 4] = b"SCR1";
15const SIGN_DOMAIN: &[u8] = b"qualia:sensing:sidecar-receipt:v1\0";
16const SIDECAR_DOMAIN: &[u8] = b"qualia:sensing:sidecar:v1\0";
17const PAYLOAD_DOMAIN: &[u8] = b"qualia:sensing:sidecar-payload:v1\0";
18const CHECKPOINT_DOMAIN: &[u8] = b"qualia:sensing:sidecar-checkpoint:v1\0";
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum SidecarReceiptError {
22    InvalidEncoding,
23    InvalidChain,
24    InvalidIdentifier,
25    BufferTooSmall,
26    PayloadBudgetExceeded,
27    SidecarMismatch,
28    PayloadMismatch,
29    InvalidSigner,
30    InvalidSignature,
31    NotAuthorized,
32}
33
34/// Immutable signed receipt. A zero policy commitment represents no supplied
35/// policy reference; authority decides whether that is permissible.
36#[derive(Clone, Copy, Debug, PartialEq, Eq)]
37pub struct SidecarReceipt {
38    signer: [u8; 32],
39    sidecar_digest: [u8; 32],
40    payload_digest: [u8; 32],
41    policy_commitment: [u8; 32],
42    chain_id: [u8; 32],
43    previous: [u8; 32],
44    sequence: u64,
45    signature: [u8; 64],
46}
47
48/// Verify current signer, subject/guardian policy and chain state. This must
49/// independently interpret the decoded sidecar and bind the payload location;
50/// neither possession of a key nor a signed policy reference grants access.
51pub trait SidecarReceiptAuthority {
52    fn permits(
53        &self,
54        receipt: &SidecarReceipt,
55        sidecar: &[u8; SIDECAR_BYTES],
56        payload: &[u8],
57    ) -> bool;
58}
59
60impl SidecarReceipt {
61    #[allow(clippy::too_many_arguments)]
62    pub fn sign(
63        sidecar: &[u8; SIDECAR_BYTES],
64        payload: &[u8],
65        payload_byte_budget: usize,
66        policy_commitment: [u8; 32],
67        chain_id: [u8; 32],
68        sequence: u64,
69        previous: Option<[u8; 32]>,
70        signing_key: &SigningKey,
71    ) -> Result<Self, SidecarReceiptError> {
72        if payload.len() > payload_byte_budget {
73            return Err(SidecarReceiptError::PayloadBudgetExceeded);
74        }
75        let previous = previous.unwrap_or([0; 32]);
76        validate_chain(&chain_id, sequence, &previous)?;
77        let mut receipt = Self {
78            signer: signing_key.verifying_key().to_bytes(),
79            sidecar_digest: digest(SIDECAR_DOMAIN, sidecar),
80            payload_digest: digest(PAYLOAD_DOMAIN, payload),
81            policy_commitment,
82            chain_id,
83            previous,
84            sequence,
85            signature: [0; 64],
86        };
87        receipt.signature = signing_key.sign(&receipt.signing_digest()).to_bytes();
88        Ok(receipt)
89    }
90
91    pub const fn signer(&self) -> &[u8; 32] {
92        &self.signer
93    }
94    pub const fn sidecar_digest(&self) -> &[u8; 32] {
95        &self.sidecar_digest
96    }
97    pub const fn payload_digest(&self) -> &[u8; 32] {
98        &self.payload_digest
99    }
100    pub const fn policy_commitment(&self) -> &[u8; 32] {
101        &self.policy_commitment
102    }
103    pub const fn chain_id(&self) -> &[u8; 32] {
104        &self.chain_id
105    }
106    pub const fn previous(&self) -> &[u8; 32] {
107        &self.previous
108    }
109    pub const fn sequence(&self) -> u64 {
110        self.sequence
111    }
112
113    /// Checks bytes and signature only. It grants no policy authority.
114    pub fn verify_signature(
115        &self,
116        sidecar: &[u8; SIDECAR_BYTES],
117        payload: &[u8],
118        payload_byte_budget: usize,
119    ) -> Result<(), SidecarReceiptError> {
120        if payload.len() > payload_byte_budget {
121            return Err(SidecarReceiptError::PayloadBudgetExceeded);
122        }
123        validate_chain(&self.chain_id, self.sequence, &self.previous)?;
124        if digest(SIDECAR_DOMAIN, sidecar) != self.sidecar_digest {
125            return Err(SidecarReceiptError::SidecarMismatch);
126        }
127        if digest(PAYLOAD_DOMAIN, payload) != self.payload_digest {
128            return Err(SidecarReceiptError::PayloadMismatch);
129        }
130        let key = VerifyingKey::from_bytes(&self.signer)
131            .map_err(|_| SidecarReceiptError::InvalidSigner)?;
132        key.verify_strict(
133            &self.signing_digest(),
134            &Signature::from_bytes(&self.signature),
135        )
136        .map_err(|_| SidecarReceiptError::InvalidSignature)
137    }
138
139    pub fn verify_with_authority(
140        &self,
141        sidecar: &[u8; SIDECAR_BYTES],
142        payload: &[u8],
143        payload_byte_budget: usize,
144        authority: &impl SidecarReceiptAuthority,
145    ) -> Result<(), SidecarReceiptError> {
146        self.verify_signature(sidecar, payload, payload_byte_budget)?;
147        if !authority.permits(self, sidecar, payload) {
148            return Err(SidecarReceiptError::NotAuthorized);
149        }
150        Ok(())
151    }
152
153    /// Hash of this complete signed receipt for the next chain position. This
154    /// does not prove that earlier receipts are available or were authorized.
155    pub fn checkpoint(&self) -> [u8; 32] {
156        let mut bytes = [0; SIDECAR_RECEIPT_BYTES];
157        self.write_to_array(&mut bytes);
158        digest(CHECKPOINT_DOMAIN, &bytes)
159    }
160
161    pub fn encode(&self, out: &mut [u8]) -> Result<usize, SidecarReceiptError> {
162        if out.len() < SIDECAR_RECEIPT_BYTES {
163            return Err(SidecarReceiptError::BufferTooSmall);
164        }
165        let mut bytes = [0; SIDECAR_RECEIPT_BYTES];
166        self.write_to_array(&mut bytes);
167        out[..SIDECAR_RECEIPT_BYTES].copy_from_slice(&bytes);
168        Ok(SIDECAR_RECEIPT_BYTES)
169    }
170
171    /// Structural decoding only; callers must verify bytes and authority.
172    pub fn decode(input: &[u8]) -> Result<Self, SidecarReceiptError> {
173        if input.len() != SIDECAR_RECEIPT_BYTES
174            || &input[..4] != MAGIC
175            || u16::from_le_bytes([input[4], input[5]]) != 1
176            || u16::from_le_bytes([input[6], input[7]]) as usize != SIDECAR_RECEIPT_BYTES
177        {
178            return Err(SidecarReceiptError::InvalidEncoding);
179        }
180        let receipt = Self {
181            signer: array32(input, 8),
182            sidecar_digest: array32(input, 40),
183            payload_digest: array32(input, 72),
184            policy_commitment: array32(input, 104),
185            chain_id: array32(input, 136),
186            previous: array32(input, 168),
187            sequence: u64::from_le_bytes(
188                input[200..208]
189                    .try_into()
190                    .map_err(|_| SidecarReceiptError::InvalidEncoding)?,
191            ),
192            signature: input[208..272]
193                .try_into()
194                .map_err(|_| SidecarReceiptError::InvalidEncoding)?,
195        };
196        validate_chain(&receipt.chain_id, receipt.sequence, &receipt.previous)?;
197        Ok(receipt)
198    }
199
200    fn signing_digest(&self) -> [u8; 32] {
201        let mut h = Sha256::new();
202        h.update(SIGN_DOMAIN);
203        h.update(self.signer);
204        h.update(self.sidecar_digest);
205        h.update(self.payload_digest);
206        h.update(self.policy_commitment);
207        h.update(self.chain_id);
208        h.update(self.previous);
209        h.update(self.sequence.to_le_bytes());
210        h.finalize().into()
211    }
212
213    fn write_to_array(&self, out: &mut [u8; SIDECAR_RECEIPT_BYTES]) {
214        out[..4].copy_from_slice(MAGIC);
215        out[4..6].copy_from_slice(&1u16.to_le_bytes());
216        out[6..8].copy_from_slice(&(SIDECAR_RECEIPT_BYTES as u16).to_le_bytes());
217        out[8..40].copy_from_slice(&self.signer);
218        out[40..72].copy_from_slice(&self.sidecar_digest);
219        out[72..104].copy_from_slice(&self.payload_digest);
220        out[104..136].copy_from_slice(&self.policy_commitment);
221        out[136..168].copy_from_slice(&self.chain_id);
222        out[168..200].copy_from_slice(&self.previous);
223        out[200..208].copy_from_slice(&self.sequence.to_le_bytes());
224        out[208..272].copy_from_slice(&self.signature);
225    }
226}
227
228fn validate_chain(
229    chain: &[u8; 32],
230    sequence: u64,
231    previous: &[u8; 32],
232) -> Result<(), SidecarReceiptError> {
233    if chain.iter().all(|b| *b == 0) {
234        return Err(SidecarReceiptError::InvalidIdentifier);
235    }
236    let genesis = previous.iter().all(|b| *b == 0);
237    if (sequence == 0) != genesis {
238        return Err(SidecarReceiptError::InvalidChain);
239    }
240    Ok(())
241}
242
243fn digest(domain: &[u8], bytes: &[u8]) -> [u8; 32] {
244    let mut h = Sha256::new();
245    h.update(domain);
246    h.update((bytes.len() as u64).to_le_bytes());
247    h.update(bytes);
248    h.finalize().into()
249}
250
251fn array32(input: &[u8], offset: usize) -> [u8; 32] {
252    let mut out = [0; 32];
253    out.copy_from_slice(&input[offset..offset + 32]);
254    out
255}
256
257#[cfg(test)]
258#[path = "sidecar_attestation_tests.rs"]
259mod tests;