1use chacha20poly1305::aead::{AeadInOut, KeyInit};
22use chacha20poly1305::XChaCha20Poly1305;
23use x25519_dalek::{PublicKey, StaticSecret};
24use zeroize::{Zeroize, ZeroizeOnDrop};
25
26const TAG_BYTES: usize = 16;
27const EPK_BYTES: usize = 32;
28const XNONCE_BYTES: usize = 24;
29
30const SEAL_KEY_CTX: &str = "q42:sanctuary:audit:seal:key:v1";
31const SEAL_NONCE_CTX: &str = "q42:sanctuary:audit:seal:nonce:v1";
32const CHAIN_HASH_LEN: usize = 32;
33
34pub const GENESIS_PARENT: [u8; CHAIN_HASH_LEN] = [0u8; CHAIN_HASH_LEN];
36
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub enum SanctuaryAuditError {
39 Rng,
40 Encrypt,
41 Decrypt,
42 Malformed,
43}
44
45fn rand_bytes<const N: usize>() -> Result<[u8; N], SanctuaryAuditError> {
46 let mut b = [0u8; N];
47 getrandom::fill(&mut b).map_err(|_| SanctuaryAuditError::Rng)?;
48 Ok(b)
49}
50
51#[derive(Zeroize, ZeroizeOnDrop)]
55pub struct AuditKeypair {
56 #[zeroize(skip)]
57 pub public: [u8; 32],
58 secret: [u8; 32],
59}
60
61impl AuditKeypair {
62 pub fn generate() -> Result<Self, SanctuaryAuditError> {
66 let secret = rand_bytes::<32>()?;
67 let public = PublicKey::from(&StaticSecret::from(secret)).to_bytes();
68 Ok(Self { public, secret })
69 }
70
71 pub fn from_secret(secret: [u8; 32]) -> Self {
76 let public = PublicKey::from(&StaticSecret::from(secret)).to_bytes();
77 Self { public, secret }
78 }
79
80 pub fn secret_bytes(&self) -> &[u8; 32] {
82 &self.secret
83 }
84}
85
86fn derive_seal_key_nonce(
87 shared: &[u8],
88 ephemeral_public: &[u8; 32],
89 recipient_public: &[u8; 32],
90) -> ([u8; 32], [u8; XNONCE_BYTES]) {
91 let mut km = Vec::with_capacity(shared.len() + 64);
93 km.extend_from_slice(shared);
94 km.extend_from_slice(ephemeral_public);
95 km.extend_from_slice(recipient_public);
96 let key = blake3::derive_key(SEAL_KEY_CTX, &km);
97 let nonce_full = blake3::derive_key(SEAL_NONCE_CTX, &km);
98 let mut nonce = [0u8; XNONCE_BYTES];
99 nonce.copy_from_slice(&nonce_full[..XNONCE_BYTES]);
100 (key, nonce)
101}
102
103fn cipher_for(key: &[u8; 32]) -> Result<XChaCha20Poly1305, SanctuaryAuditError> {
104 let key =
105 <&chacha20poly1305::Key>::try_from(&key[..]).map_err(|_| SanctuaryAuditError::Encrypt)?;
106 Ok(XChaCha20Poly1305::new(key))
107}
108
109fn aead_seal(
110 key: &[u8; 32],
111 nonce: &[u8; XNONCE_BYTES],
112 plaintext: &[u8],
113 aad: &[u8],
114) -> Result<Vec<u8>, SanctuaryAuditError> {
115 let cipher = cipher_for(key)?;
116 let nonce = <&chacha20poly1305::XNonce>::try_from(&nonce[..])
117 .map_err(|_| SanctuaryAuditError::Encrypt)?;
118 let mut buffer = plaintext.to_vec();
119 let tag = cipher
120 .encrypt_inout_detached(nonce, aad, buffer.as_mut_slice().into())
121 .map_err(|_| SanctuaryAuditError::Encrypt)?;
122 buffer.extend_from_slice(tag.as_slice());
123 Ok(buffer)
124}
125
126fn aead_open(
127 key: &[u8; 32],
128 nonce: &[u8; XNONCE_BYTES],
129 ct_and_tag: &[u8],
130 aad: &[u8],
131) -> Result<Vec<u8>, SanctuaryAuditError> {
132 if ct_and_tag.len() < TAG_BYTES {
133 return Err(SanctuaryAuditError::Malformed);
134 }
135 let split = ct_and_tag.len() - TAG_BYTES;
136 let (ct, tag_bytes) = ct_and_tag.split_at(split);
137 let cipher = cipher_for(key)?;
138 let nonce = <&chacha20poly1305::XNonce>::try_from(&nonce[..])
139 .map_err(|_| SanctuaryAuditError::Decrypt)?;
140 let tag = <&chacha20poly1305::Tag>::try_from(tag_bytes)
141 .map_err(|_| SanctuaryAuditError::Malformed)?;
142 let mut buffer = ct.to_vec();
143 cipher
144 .decrypt_inout_detached(nonce, aad, buffer.as_mut_slice().into(), tag)
145 .map_err(|_| SanctuaryAuditError::Decrypt)?;
146 Ok(buffer)
147}
148
149pub fn seal_to(
153 recipient_public: &[u8; 32],
154 plaintext: &[u8],
155 aad: &[u8],
156) -> Result<Vec<u8>, SanctuaryAuditError> {
157 let ephemeral_secret = StaticSecret::from(rand_bytes::<32>()?);
158 let ephemeral_public = PublicKey::from(&ephemeral_secret).to_bytes();
159 let shared = ephemeral_secret.diffie_hellman(&PublicKey::from(*recipient_public));
160 let (key, nonce) =
161 derive_seal_key_nonce(shared.as_bytes(), &ephemeral_public, recipient_public);
162 let body = aead_seal(&key, &nonce, plaintext, aad)?;
163 let mut out = Vec::with_capacity(EPK_BYTES + body.len());
164 out.extend_from_slice(&ephemeral_public);
165 out.extend_from_slice(&body);
166 Ok(out)
167}
168
169pub fn open_sealed(
172 recipient_secret: &[u8; 32],
173 sealed: &[u8],
174 aad: &[u8],
175) -> Result<Vec<u8>, SanctuaryAuditError> {
176 if sealed.len() < EPK_BYTES + TAG_BYTES {
177 return Err(SanctuaryAuditError::Malformed);
178 }
179 let mut ephemeral_public = [0u8; 32];
180 ephemeral_public.copy_from_slice(&sealed[..EPK_BYTES]);
181 let body = &sealed[EPK_BYTES..];
182
183 let secret = StaticSecret::from(*recipient_secret);
184 let recipient_public = PublicKey::from(&secret).to_bytes();
185 let shared = secret.diffie_hellman(&PublicKey::from(ephemeral_public));
186 let (key, nonce) =
187 derive_seal_key_nonce(shared.as_bytes(), &ephemeral_public, &recipient_public);
188 aead_open(&key, &nonce, body, aad)
189}
190
191pub fn wrap_key(
194 wrapping_key: &[u8; 32],
195 key_material: &[u8],
196 aad: &[u8],
197) -> Result<Vec<u8>, SanctuaryAuditError> {
198 let nonce = rand_bytes::<XNONCE_BYTES>()?;
199 let body = aead_seal(wrapping_key, &nonce, key_material, aad)?;
200 let mut out = Vec::with_capacity(XNONCE_BYTES + body.len());
201 out.extend_from_slice(&nonce);
202 out.extend_from_slice(&body);
203 Ok(out)
204}
205
206pub fn unwrap_key(
208 wrapping_key: &[u8; 32],
209 wrapped: &[u8],
210 aad: &[u8],
211) -> Result<Vec<u8>, SanctuaryAuditError> {
212 if wrapped.len() < XNONCE_BYTES + TAG_BYTES {
213 return Err(SanctuaryAuditError::Malformed);
214 }
215 let mut nonce = [0u8; XNONCE_BYTES];
216 nonce.copy_from_slice(&wrapped[..XNONCE_BYTES]);
217 aead_open(wrapping_key, &nonce, &wrapped[XNONCE_BYTES..], aad)
218}
219
220pub fn chain_hash(parent: &[u8; CHAIN_HASH_LEN], payload: &[u8]) -> [u8; CHAIN_HASH_LEN] {
224 let mut hasher = blake3::Hasher::new();
225 hasher.update(parent);
226 hasher.update(payload);
227 *hasher.finalize().as_bytes()
228}
229
230#[cfg(test)]
231mod tests {
232 use super::*;
233
234 #[test]
235 fn sealed_box_round_trips() {
236 let kp = AuditKeypair::generate().unwrap();
237 let msg = b"decoy session 1: coercer added note at 12:04";
238 let sealed = seal_to(&kp.public, msg, b"branch:session-1").unwrap();
239 let opened = open_sealed(kp.secret_bytes(), &sealed, b"branch:session-1").unwrap();
240 assert_eq!(opened, msg);
241 }
242
243 #[test]
244 fn only_the_secret_holder_can_open() {
245 let kp = AuditKeypair::generate().unwrap();
246 let other = AuditKeypair::generate().unwrap();
247 let sealed = seal_to(&kp.public, b"evidence", b"").unwrap();
248 assert!(open_sealed(other.secret_bytes(), &sealed, b"").is_err());
249 }
250
251 #[test]
252 fn public_key_alone_cannot_read() {
253 let kp = AuditKeypair::generate().unwrap();
256 let sealed = seal_to(&kp.public, b"only-the-real-lane-reads-this", b"").unwrap();
257 match open_sealed(&kp.public, &sealed, b"") {
258 Err(_) => {}
259 Ok(pt) => assert_ne!(pt.as_slice(), b"only-the-real-lane-reads-this"),
260 }
261 }
262
263 #[test]
264 fn tampered_sealed_box_is_rejected() {
265 let kp = AuditKeypair::generate().unwrap();
266 let mut sealed = seal_to(&kp.public, b"unaltered", b"").unwrap();
267 let mid = sealed.len() / 2;
268 sealed[mid] ^= 0xFF;
269 assert!(open_sealed(kp.secret_bytes(), &sealed, b"").is_err());
270 }
271
272 #[test]
273 fn aad_is_bound() {
274 let kp = AuditKeypair::generate().unwrap();
275 let sealed = seal_to(&kp.public, b"m", b"branch:session-1").unwrap();
276 assert!(open_sealed(kp.secret_bytes(), &sealed, b"branch:session-2").is_err());
277 }
278
279 #[test]
280 fn sealing_is_non_deterministic() {
281 let kp = AuditKeypair::generate().unwrap();
284 let a = seal_to(&kp.public, b"same-note", b"").unwrap();
285 let b = seal_to(&kp.public, b"same-note", b"").unwrap();
286 assert_ne!(a, b);
287 }
288
289 #[test]
290 fn key_wrap_round_trips_and_binds_key_and_aad() {
291 let real_key = rand_bytes::<32>().unwrap();
292 let decoy_key = [7u8; 32];
293 let wrapped = wrap_key(&real_key, &decoy_key, b"role:decoy-lane-key").unwrap();
294 assert_eq!(
295 unwrap_key(&real_key, &wrapped, b"role:decoy-lane-key").unwrap(),
296 decoy_key
297 );
298 assert!(unwrap_key(&[9u8; 32], &wrapped, b"role:decoy-lane-key").is_err());
300 assert!(unwrap_key(&real_key, &wrapped, b"role:something-else").is_err());
302 }
303
304 #[test]
305 fn hash_chain_is_deterministic_and_tamper_evident() {
306 let r1 = chain_hash(&GENESIS_PARENT, b"session-1 opened");
307 let r2 = chain_hash(&r1, b"note added: 'call me'");
308 let r3 = chain_hash(&r2, b"note edited");
309
310 assert_eq!(r1, chain_hash(&GENESIS_PARENT, b"session-1 opened"));
312 assert_ne!(r1, r2);
313 assert_ne!(r2, r3);
314
315 let r2_tampered = chain_hash(&r1, b"note added: 'do NOT call'");
317 assert_ne!(r2, r2_tampered);
318 assert_ne!(r3, chain_hash(&r2_tampered, b"note edited"));
319 }
320}