Skip to main content

qualia_core_db/sensing/acquisition/storage/
custody.rs

1//! Durable local custody publication and verified readback for approved schemas 6/7.
2//!
3//! Callers must hold an exclusive lease over a trusted local root. Redirect and
4//! reparse checks reject final-component links; ancestors require host custody.
5use super::*;
6use crate::{
7    q42::{field_envelope as env, field_semantics as sem},
8    sensing::acquisition as a,
9};
10use std::{
11    fs::{self, File, OpenOptions},
12    io::{self, Read, Write},
13    path::{Component, Path, PathBuf},
14    sync::atomic::{AtomicU64, Ordering},
15};
16
17const MAX_CUSTODY_ENTRIES: usize = 65;
18static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
19
20#[derive(Clone, Copy, Debug)]
21pub struct PublishOptions {
22    pub max_bytes: usize,
23    pub envelope: env::Limits,
24    pub shared: sem::Limits,
25    pub limits: Limits,
26}
27
28impl Default for PublishOptions {
29    fn default() -> Self {
30        Self {
31            max_bytes: 256 * 1024 * 1024,
32            envelope: env::Limits::default(),
33            shared: sem::Limits::default(),
34            limits: Limits::default(),
35        }
36    }
37}
38
39#[derive(Clone, Debug, PartialEq, Eq)]
40pub struct PublishedArtifact {
41    pub blake3: [u8; 32],
42    pub byte_length: u64,
43    pub family: Family,
44    pub path: PathBuf,
45}
46
47#[derive(Debug)]
48pub enum PublishError {
49    Io(io::Error),
50    Budget,
51    InvalidPath,
52    Conflict,
53    Admission(Error),
54}
55
56impl From<io::Error> for PublishError {
57    fn from(error: io::Error) -> Self {
58        Self::Io(error)
59    }
60}
61
62impl From<Error> for PublishError {
63    fn from(error: Error) -> Self {
64        Self::Admission(error)
65    }
66}
67
68impl std::fmt::Display for PublishError {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        match self {
71            Self::Io(e) => write!(f, "acquisition custody IO: {e}"),
72            Self::Budget => f.write_str("acquisition custody byte budget exceeded"),
73            Self::InvalidPath => f.write_str("acquisition custody path redirects or is unsafe"),
74            Self::Conflict => f.write_str("acquisition custody destination bytes mismatch"),
75            Self::Admission(e) => write!(f, "acquisition custody admission failed: {e:?}"),
76        }
77    }
78}
79
80impl std::error::Error for PublishError {}
81
82struct StagingGuard(Option<PathBuf>);
83impl StagingGuard {
84    fn path(&self) -> Result<&Path, PublishError> {
85        self.0.as_deref().ok_or(PublishError::InvalidPath)
86    }
87}
88impl Drop for StagingGuard {
89    fn drop(&mut self) {
90        if let Some(path) = self.0.take() {
91            let _ = fs::remove_file(path);
92        }
93    }
94}
95
96fn validate_root(root: &Path) -> Result<(), PublishError> {
97    if !root.is_absolute() || root.as_os_str().len() > 4096 {
98        return Err(PublishError::InvalidPath);
99    }
100    if root.components().any(|part| matches!(part, Component::ParentDir)) {
101        return Err(PublishError::InvalidPath);
102    }
103    #[cfg(windows)]
104    {
105        use std::path::Prefix;
106        if !matches!(
107            root.components().next(),
108            Some(Component::Prefix(prefix))
109                if matches!(prefix.kind(), Prefix::Disk(_) | Prefix::VerbatimDisk(_))
110        ) {
111            return Err(PublishError::InvalidPath);
112        }
113    }
114    Ok(())
115}
116
117fn check_no_reparse(meta: &fs::Metadata) -> Result<(), PublishError> {
118    if meta.file_type().is_symlink() {
119        return Err(PublishError::InvalidPath);
120    }
121    #[cfg(windows)]
122    {
123        use std::os::windows::fs::MetadataExt;
124        const ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
125        if meta.file_attributes() & ATTRIBUTE_REPARSE_POINT != 0 {
126            return Err(PublishError::InvalidPath);
127        }
128    }
129    Ok(())
130}
131
132fn child_dir(parent: &Path, name: &str) -> Result<PathBuf, PublishError> {
133    let path = parent.join(name);
134    match fs::create_dir(&path) {
135        Ok(()) => {}
136        Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {}
137        Err(e) => return Err(e.into()),
138    }
139    let meta = fs::symlink_metadata(&path)?;
140    check_no_reparse(&meta)?;
141    if !meta.is_dir() {
142        return Err(PublishError::InvalidPath);
143    }
144    let canonical = path.canonicalize()?;
145    if canonical.parent() != Some(parent) {
146        return Err(PublishError::InvalidPath);
147    }
148    Ok(canonical)
149}
150
151fn storage_dir(root: &Path, create: bool) -> Result<PathBuf, PublishError> {
152    validate_root(root)?;
153    if create {
154        fs::create_dir_all(root)?;
155    }
156    let canonical_root = root.canonicalize()?;
157    if create {
158        return child_dir(&child_dir(&canonical_root, "sensing")?, "acquisition");
159    }
160    let sensing = canonical_root.join("sensing");
161    let sm = fs::symlink_metadata(&sensing)?;
162    check_no_reparse(&sm)?;
163    if !sm.is_dir() {
164        return Err(PublishError::InvalidPath);
165    }
166    let acq = sensing.canonicalize()?.join("acquisition");
167    let am = fs::symlink_metadata(&acq)?;
168    check_no_reparse(&am)?;
169    if !am.is_dir() {
170        return Err(PublishError::InvalidPath);
171    }
172    let canonical = acq.canonicalize()?;
173    if canonical.parent() != sensing.canonicalize().ok().as_deref() {
174        return Err(PublishError::InvalidPath);
175    }
176    Ok(canonical)
177}
178
179fn open_regular(path: &Path) -> Result<File, PublishError> {
180    let pre = fs::symlink_metadata(path)?;
181    check_no_reparse(&pre)?;
182    if !pre.is_file() {
183        return Err(PublishError::InvalidPath);
184    }
185    let mut options = OpenOptions::new();
186    options.read(true);
187    #[cfg(windows)]
188    {
189        use std::os::windows::fs::OpenOptionsExt;
190        const OPEN_REPARSE_POINT: u32 = 0x0020_0000;
191        options.custom_flags(OPEN_REPARSE_POINT);
192    }
193    let file = options.open(path)?;
194    let meta = file.metadata()?;
195    check_no_reparse(&meta)?;
196    if !meta.is_file() {
197        return Err(PublishError::InvalidPath);
198    }
199    Ok(file)
200}
201
202fn verify_exact(path: &Path, bytes: &[u8]) -> Result<(), PublishError> {
203    let mut file = open_regular(path)?;
204    if file.metadata()?.len() != bytes.len() as u64 {
205        return Err(PublishError::Conflict);
206    }
207    let mut scratch = [0u8; 8192];
208    for expected in bytes.chunks(scratch.len()) {
209        file.read_exact(&mut scratch[..expected.len()])?;
210        if &scratch[..expected.len()] != expected {
211            return Err(PublishError::Conflict);
212        }
213    }
214    if file.read(&mut scratch[..1])? != 0 {
215        return Err(PublishError::Conflict);
216    }
217    Ok(())
218}
219
220fn create_staging(dir: &Path, bytes: &[u8]) -> Result<StagingGuard, PublishError> {
221    let pid = std::process::id();
222    for _ in 0..64 {
223        let seq = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
224        let candidate = dir.join(format!(".tmp-acq-{pid}-{seq}.part"));
225        let mut options = OpenOptions::new();
226        options.write(true).create_new(true);
227        #[cfg(unix)]
228        {
229            use std::os::unix::fs::OpenOptionsExt;
230            options.mode(0o600);
231        }
232        match options.open(&candidate) {
233            Ok(mut file) => {
234                let guard = StagingGuard(Some(candidate));
235                file.write_all(bytes)?;
236                file.sync_all()?;
237                return Ok(guard);
238            }
239            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue,
240            Err(e) => return Err(e.into()),
241        }
242    }
243    Err(PublishError::Io(io::Error::new(
244        io::ErrorKind::AlreadyExists,
245        "exhausted staging filenames",
246    )))
247}
248
249fn extension(family: Family) -> &'static str {
250    match family {
251        Family::QacV1Candidate => "qac",
252        Family::EmfV4Candidate => "emf",
253    }
254}
255
256/// Admit `bytes` under `family` (schemas 6/7) and atomically publish without
257/// overwriting an existing destination. Existing matching content is verified.
258pub fn publish_container(
259    root: &Path,
260    family: Family,
261    selected: u32,
262    bytes: &[u8],
263    scratch: &mut sem::Scratch<'_>,
264    options: PublishOptions,
265) -> Result<PublishedArtifact, PublishError> {
266    validate_root(root)?;
267    if bytes.len() > options.max_bytes {
268        return Err(PublishError::Budget);
269    }
270    let structural = env::StructuralView::open(bytes, family, options.envelope)
271        .map_err(Error::from)?;
272    if structural.entry_count() as usize > MAX_CUSTODY_ENTRIES {
273        return Err(Error::Scratch.into());
274    }
275    let mut originals = [None; MAX_CUSTODY_ENTRIES];
276    let _doc = admit(
277        &structural,
278        selected,
279        &mut originals,
280        scratch,
281        options.shared,
282        options.limits,
283    )?;
284    let digest = *blake3::hash(bytes).as_bytes();
285    let dir = storage_dir(root, true)?;
286    let mut hex = String::with_capacity(64);
287    for byte in digest {
288        use std::fmt::Write as _;
289        let _ = write!(&mut hex, "{byte:02x}");
290    }
291    let dest = dir.join(format!("{hex}.{}", extension(family)));
292    let guard = create_staging(&dir, bytes)?;
293    match fs::hard_link(guard.path()?, &dest) {
294        Ok(()) => {}
295        Err(e) if e.kind() == io::ErrorKind::AlreadyExists => verify_exact(&dest, bytes)?,
296        Err(e) => return Err(e.into()),
297    }
298    Ok(PublishedArtifact {
299        blake3: digest,
300        byte_length: bytes.len() as u64,
301        family,
302        path: dest,
303    })
304}
305
306/// Read an acquisition artifact into caller-owned `buffer` and re-admit it.
307pub fn read_container<'a, 's>(
308    root: &Path,
309    family: Family,
310    digest: &[u8; 32],
311    selected: u32,
312    buffer: &'a mut [u8],
313    originals: &'s mut [Option<a::Original<'a>>],
314    scratch: &mut sem::Scratch<'_>,
315    options: PublishOptions,
316) -> Result<(usize, PublishedArtifact, Document<'a, 's>), PublishError> {
317    let dir = storage_dir(root, false)?;
318    let mut hex = String::with_capacity(64);
319    for byte in *digest {
320        use std::fmt::Write as _;
321        let _ = write!(&mut hex, "{byte:02x}");
322    }
323    let path = dir.join(format!("{hex}.{}", extension(family)));
324    let mut file = open_regular(&path)?;
325    let file_len = file.metadata()?.len();
326    let len = usize::try_from(file_len).map_err(|_| PublishError::Budget)?;
327    if len > options.max_bytes || len > buffer.len() {
328        return Err(PublishError::Budget);
329    }
330    file.read_exact(&mut buffer[..len])?;
331    let mut extra = [0u8; 1];
332    if file.read(&mut extra)? != 0 {
333        return Err(PublishError::Conflict);
334    }
335    let bytes = &buffer[..len];
336    let actual_digest = *blake3::hash(bytes).as_bytes();
337    if actual_digest != *digest {
338        return Err(PublishError::Conflict);
339    }
340    let structural = env::StructuralView::open(bytes, family, options.envelope)
341        .map_err(Error::from)?;
342    let doc = admit(
343        &structural,
344        selected,
345        originals,
346        scratch,
347        options.shared,
348        options.limits,
349    )?;
350    let artifact = PublishedArtifact {
351        blake3: actual_digest,
352        byte_length: len as u64,
353        family,
354        path,
355    };
356    Ok((len, artifact, doc))
357}
358
359#[cfg(test)]
360#[path = "custody_tests.rs"]
361mod tests;