Skip to main content

arachne_store/
lib.rs

1//! Encrypted, atomic local records. No transport, group protocol or payload types.
2//! The host supplies a private directory, protected root key and expected scope.
3use aes_gcm::{
4    Aes256Gcm, KeyInit,
5    aead::{Aead, Payload},
6};
7use rusqlite::{Connection, OptionalExtension, TransactionBehavior, params};
8use sha2::{Digest, Sha256};
9use std::{
10    collections::{BTreeMap, BTreeSet},
11    path::Path,
12};
13use zeroize::Zeroizing;
14
15pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
16/// None deletes a record. An empty value is a valid stored value.
17pub type Change<'a> = (&'a [u8], Option<&'a [u8]>);
18pub const MAX_RECORD_BYTES: usize = 1024 * 1024;
19const MAX_KEY_BYTES: usize = 1024;
20const OVERHEAD: usize = 12 + 16;
21const RECORD_SCHEMA: &str =
22    "CREATE TABLE records (name BLOB PRIMARY KEY, sealed BLOB NOT NULL) WITHOUT ROWID";
23const HEAD_SCHEMA: &str =
24    "CREATE TABLE head (id INTEGER PRIMARY KEY CHECK(id=0), sealed BLOB NOT NULL)";
25type Index = BTreeMap<Vec<u8>, [u8; 32]>;
26
27/// Caller-owned proof of the accepted record head. Persist it outside the
28/// store when rollback detection must survive a whole-file restore.
29#[derive(Clone, Copy, Debug, Eq, PartialEq)]
30pub struct FreshnessAnchor {
31    pub revision: u64,
32    pub digest: [u8; 32],
33}
34
35/// One exclusive local owner. Reopen authenticates every retained record before
36/// exposing state. Whole-store rollback requires an external anchor to detect.
37pub struct Store {
38    connection: Connection,
39    key: Zeroizing<[u8; 32]>,
40    scope: [u8; 32],
41    revision: u64,
42    index: Index,
43}
44
45fn index_digest(index: &Index) -> [u8; 32] {
46    let mut hash = Sha256::new();
47    hash.update(b"data-fabric/record-index/v1");
48    for (name, digest) in index {
49        hash.update((name.len() as u32).to_be_bytes());
50        hash.update(name);
51        hash.update(digest);
52    }
53    hash.finalize().into()
54}
55
56impl Store {
57    pub fn open(path: &Path, root: &[u8; 32], scope: [u8; 32]) -> Result<Self> {
58        // Ciphertext files only; the caller owns the parent directory and lock
59        // lifecycle. SQLite's exclusive mode prevents concurrent DB owners.
60        let mut options = std::fs::OpenOptions::new();
61        options.write(true).create_new(true);
62        #[cfg(unix)]
63        {
64            use std::os::unix::fs::OpenOptionsExt;
65            options.mode(0o600);
66        }
67        let is_new = match options.open(path) {
68            Ok(file) => {
69                drop(file);
70                true
71            }
72            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => false,
73            Err(error) => return Err(error.into()),
74        };
75        let connection = Connection::open(path)?;
76        connection.busy_timeout(std::time::Duration::from_millis(100))?;
77        connection.set_limit(
78            rusqlite::limits::Limit::SQLITE_LIMIT_LENGTH,
79            (MAX_RECORD_BYTES + MAX_KEY_BYTES + 4096) as i32,
80        );
81        connection.execute_batch(
82            "PRAGMA locking_mode=EXCLUSIVE;
83             PRAGMA journal_mode=DELETE;
84             PRAGMA synchronous=FULL;
85             PRAGMA secure_delete=ON;
86             PRAGMA trusted_schema=OFF;",
87        )?;
88        let mut key = Zeroizing::new([0; 32]);
89        hkdf::Hkdf::<Sha256>::new(Some(b"data-fabric/record-store/v1"), root)
90            .expand(&scope, key.as_mut())
91            .map_err(|_| "storage key derivation failed")?;
92        let mut store = Self {
93            connection,
94            key,
95            scope,
96            revision: 0,
97            index: Index::new(),
98        };
99        if is_new {
100            let head = store.seal_head(0, &store.index)?;
101            let tx = store
102                .connection
103                .transaction_with_behavior(TransactionBehavior::Immediate)?;
104            tx.execute(RECORD_SCHEMA, [])?;
105            tx.execute(HEAD_SCHEMA, [])?;
106            tx.execute("INSERT INTO head(id,sealed) VALUES(0,?1)", [&head])?;
107            tx.commit()?;
108            return Ok(store);
109        }
110        // An untrusted DB must not install triggers that silently alter commits.
111        let schema: Vec<(String, String)> = store
112            .connection
113            .prepare(
114                "SELECT name,sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' ORDER BY name",
115            )?
116            .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
117            .collect::<std::result::Result<_, _>>()?;
118        if schema
119            != [
120                ("head".into(), HEAD_SCHEMA.into()),
121                ("records".into(), RECORD_SCHEMA.into()),
122            ]
123        {
124            return Err("unexpected record store schema".into());
125        }
126        let sealed: Option<Vec<u8>> = store
127            .connection
128            .query_row("SELECT sealed FROM head WHERE id=0", [], |row| row.get(0))
129            .optional()?;
130        let sealed = sealed.ok_or("record head missing")?;
131        if sealed.len() != OVERHEAD + 40 {
132            return Err("invalid record head".into());
133        }
134        let head = store.unseal(0, b"", &sealed)?;
135        store.revision = u64::from_be_bytes(head[..8].try_into()?);
136        {
137            let mut statement = store
138                .connection
139                .prepare("SELECT name,sealed FROM records ORDER BY name")?;
140            let mut rows = statement.query([])?;
141            while let Some(row) = rows.next()? {
142                let name = row.get_ref(0)?.as_blob()?;
143                let sealed = row.get_ref(1)?.as_blob()?;
144                Self::validate_key(name)?;
145                if !(OVERHEAD..=OVERHEAD + MAX_RECORD_BYTES).contains(&sealed.len()) {
146                    return Err("invalid encrypted record size".into());
147                }
148                store
149                    .index
150                    .insert(name.to_vec(), Sha256::digest(sealed).into());
151            }
152        }
153        if head[8..] != index_digest(&store.index) {
154            return Err("record set authentication failed".into());
155        }
156        Ok(store)
157    }
158
159    pub fn revision(&self) -> u64 {
160        self.revision
161    }
162
163    pub fn freshness(&self) -> FreshnessAnchor {
164        FreshnessAnchor {
165            revision: self.revision,
166            digest: index_digest(&self.index),
167        }
168    }
169
170    pub fn verify_freshness(&self, expected: FreshnessAnchor) -> Result<()> {
171        if self.freshness() != expected {
172            return Err("record store freshness anchor mismatch".into());
173        }
174        Ok(())
175    }
176
177    /// Keys from the authenticated accepted index, in byte order. Values still
178    /// pass their integrity check when read; no plaintext values are retained here.
179    pub fn keys<'a>(&'a self, prefix: &'a [u8]) -> impl Iterator<Item = &'a [u8]> + 'a {
180        self.index
181            .range(prefix.to_vec()..)
182            .take_while(move |(name, _)| name.starts_with(prefix))
183            .map(|(name, _)| name.as_slice())
184    }
185
186    pub fn get(&self, name: &[u8]) -> Result<Option<Zeroizing<Vec<u8>>>> {
187        Self::validate_key(name)?;
188        let value: Option<Vec<u8>> = self
189            .connection
190            .query_row("SELECT sealed FROM records WHERE name=?1", [name], |r| {
191                r.get(0)
192            })
193            .optional()?;
194        match (self.index.get(name), value) {
195            (None, None) => Ok(None),
196            (Some(expected), Some(sealed))
197                if *expected == <[u8; 32]>::from(Sha256::digest(&sealed)) =>
198            {
199                Ok(Some(self.unseal(1, name, &sealed)?))
200            }
201            _ => Err("record differs from accepted head".into()),
202        }
203    }
204
205    /// Commit the complete operation before adopting its state or emitting its
206    /// packets. A failed commit leaves this owner at the prior revision; if I/O
207    /// makes the outcome uncertain, close/reopen before attempting another write.
208    pub fn commit(&mut self, expected_revision: u64, changes: &[Change<'_>]) -> Result<u64> {
209        if expected_revision != self.revision {
210            return Err("stale record revision".into());
211        }
212        let prior: Vec<u8> =
213            self.connection
214                .query_row("SELECT sealed FROM head WHERE id=0", [], |row| row.get(0))?;
215        let prior = self.unseal(0, b"", &prior)?;
216        if prior.len() != 40
217            || prior[..8] != self.revision.to_be_bytes()
218            || prior[8..] != index_digest(&self.index)
219        {
220            return Err("record head differs from accepted state".into());
221        }
222        let revision = self
223            .revision
224            .checked_add(1)
225            .ok_or("record revision exhausted")?;
226        let mut names = BTreeSet::new();
227        let mut sealed = Vec::with_capacity(changes.len());
228        // ponytail: O(record count) index copy/hash, but only changed ciphertext
229        // rows are rewritten; introduce an incremental index if measurement needs it.
230        let mut index = self.index.clone();
231        for (name, value) in changes {
232            Self::validate_key(name)?;
233            if !names.insert(*name) {
234                return Err("duplicate record change".into());
235            }
236            let value = match value {
237                Some(value) => {
238                    if value.len() > MAX_RECORD_BYTES {
239                        return Err("record exceeds byte budget".into());
240                    }
241                    let packet = self.seal(1, name, value)?;
242                    index.insert(name.to_vec(), Sha256::digest(&packet).into());
243                    Some(packet)
244                }
245                None => {
246                    index.remove(*name);
247                    None
248                }
249            };
250            sealed.push((*name, value));
251        }
252        let head = self.seal_head(revision, &index)?;
253        let tx = self
254            .connection
255            .transaction_with_behavior(TransactionBehavior::Immediate)?;
256        for (name, value) in &sealed {
257            match value {
258                Some(value) => {
259                    tx.execute(
260                    "INSERT INTO records(name,sealed) VALUES(?1,?2) ON CONFLICT(name) DO UPDATE SET sealed=excluded.sealed",
261                    params![name, value],
262                )?;
263                }
264                None => {
265                    tx.execute("DELETE FROM records WHERE name=?1", [name])?;
266                }
267            }
268        }
269        tx.execute("UPDATE head SET sealed=?1 WHERE id=0", [&head])?;
270        tx.commit()?;
271        self.index = index;
272        self.revision = revision;
273        Ok(revision)
274    }
275
276    fn validate_key(name: &[u8]) -> Result<()> {
277        if name.is_empty() || name.len() > MAX_KEY_BYTES {
278            return Err("invalid record key".into());
279        }
280        Ok(())
281    }
282    fn aad(&self, kind: u8, name: &[u8]) -> Vec<u8> {
283        let mut aad = b"data-fabric/record/v1".to_vec();
284        aad.extend(self.scope);
285        aad.push(kind);
286        aad.extend((name.len() as u32).to_be_bytes());
287        aad.extend(name);
288        aad
289    }
290    fn seal_head(&self, revision: u64, index: &Index) -> Result<Vec<u8>> {
291        let mut plain = Zeroizing::new(revision.to_be_bytes().to_vec());
292        plain.extend(index_digest(index));
293        self.seal(0, b"", &plain)
294    }
295    fn seal(&self, kind: u8, name: &[u8], plain: &[u8]) -> Result<Vec<u8>> {
296        let mut nonce = [0; 12];
297        getrandom::getrandom(&mut nonce).map_err(|_| "record randomness failed")?;
298        let cipher =
299            Aes256Gcm::new_from_slice(self.key.as_ref()).map_err(|_| "invalid storage key")?;
300        let mut packet = nonce.to_vec();
301        packet.extend(
302            cipher
303                .encrypt(
304                    (&nonce).into(),
305                    Payload {
306                        msg: plain,
307                        aad: &self.aad(kind, name),
308                    },
309                )
310                .map_err(|_| "record protection failed")?,
311        );
312        Ok(packet)
313    }
314    fn unseal(&self, kind: u8, name: &[u8], sealed: &[u8]) -> Result<Zeroizing<Vec<u8>>> {
315        if sealed.len() < OVERHEAD {
316            return Err("truncated encrypted record".into());
317        }
318        let cipher =
319            Aes256Gcm::new_from_slice(self.key.as_ref()).map_err(|_| "invalid storage key")?;
320        let nonce: &[u8; 12] = sealed[..12].try_into()?;
321        Ok(Zeroizing::new(
322            cipher
323                .decrypt(
324                    nonce.into(),
325                    Payload {
326                        msg: &sealed[12..],
327                        aad: &self.aad(kind, name),
328                    },
329                )
330                .map_err(|_| "record authentication failed")?,
331        ))
332    }
333}
334
335#[cfg(test)]
336mod tests;