Skip to main content

eggpack_core/
digest.rs

1//! The single producer-side file-digest authority.
2//!
3//! `eggpack-core` owns exactly one way to turn a file into a byte count and a
4//! lowercase hex SHA-256 digest. Manifest aggregation, local finalization, and
5//! candidate qualification all route through [`file_digest`], so a recorded
6//! digest always describes the bytes of the exact regular file that was
7//! inspected. `eggpack-ci` and `eggpack-github` consume the same helper rather
8//! than re-implementing one.
9//!
10//! A digest is an integrity fact about bytes only. Nothing here produces or
11//! asserts a signature, a provenance chain, or a publisher identity.
12
13use sha2::{Digest, Sha256};
14use std::{
15    fs::{self, File},
16    io::Read,
17    path::Path,
18};
19
20/// Fixed streaming buffer size for file digests.
21///
22/// The digest never holds a whole artifact in memory: a finalized release
23/// bundle can be far larger than the process should grow to accommodate.
24const DIGEST_BUFFER_BYTES: usize = 64 * 1024;
25
26/// Why a file digest was refused.
27///
28/// Every variant is a hard failure of the enclosing operation. There is no
29/// sentinel digest, no partial record, and no retry against the same path.
30#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31pub enum DigestError {
32    /// The path could not be inspected.
33    Unavailable,
34    /// The path is not a regular non-symlink file.
35    NotRegularFile,
36    /// The file is empty; a zero-length input never produces a digest record.
37    Empty,
38    /// The file could not be opened for reading.
39    OpenFailed,
40    /// The file could not be read to its end.
41    ReadFailed,
42    /// The accumulated byte count overflowed `u64`.
43    SizeOverflow,
44    /// The path changed while it was being read.
45    ChangedDuringRead,
46}
47
48impl DigestError {
49    /// Bounded, single-line reason phrase for this refusal.
50    ///
51    /// The phrase is a fragment: a caller prefixes the subject it was
52    /// digesting, so no diagnostic loses the context it had before the
53    /// producer converged on one helper.
54    pub fn reason(self) -> &'static str {
55        match self {
56            Self::Unavailable => "is unavailable",
57            Self::NotRegularFile => "is not a regular non-symlink file",
58            Self::Empty => "must be non-empty",
59            Self::OpenFailed => "cannot be opened",
60            Self::ReadFailed => "read failed",
61            Self::SizeOverflow => "size overflow",
62            Self::ChangedDuringRead => "changed during read",
63        }
64    }
65}
66
67impl std::fmt::Display for DigestError {
68    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
69        write!(f, "digest input {}", self.reason())
70    }
71}
72
73impl std::error::Error for DigestError {}
74
75/// Digest one regular file into its byte count and its lowercase hex SHA-256.
76///
77/// This is the **single** producer-side file-digest authority. It refuses, in
78/// this order:
79///
80/// 1. the path is inspected with `symlink_metadata`, so a symlink is never
81///    followed and a non-regular file is refused;
82/// 2. an empty file is refused **before** it is read, so a zero-length input
83///    can never produce a digest record;
84/// 3. the bytes are streamed through a fixed 64 KiB buffer and the byte count
85///    is accumulated with overflow checking, so a large artifact never grows
86///    the process to accommodate it;
87/// 4. a read that produced zero bytes is refused, so a file truncated to
88///    nothing between step 1 and the read cannot produce a digest record
89///    either;
90/// 5. the path is inspected again with `symlink_metadata` after the read, and
91///    the digest is refused if the path became a symlink, stopped being a
92///    regular file, or changed length while it was read.
93///
94/// Step 4 is not redundant with step 2: step 2 observes the length *before*
95/// the read, and a file truncated in between would otherwise be read as zero
96/// bytes and pass the step 5 comparison, because the post-read length would
97/// equal the zero bytes read.
98///
99/// Step 5 is the time-of-check/time-of-use guard. The symlink rejection in
100/// step 1 is a property of the path policy, so it stays a path observation;
101/// the read then happens through the handle that was opened, and the evidence
102/// recorded is of those bytes. Without the post-read re-check, a path
103/// replaced between the check and the open could make the digest describe
104/// some other file than the one that was inspected, and a file rewritten
105/// mid-read could produce a size and a digest that disagree with each other.
106///
107/// The hashed bytes are unchanged by this helper: the hash function, the
108/// encoding, and the lowercase hex representation are exactly what the
109/// producer has always recorded.
110pub fn file_digest(path: &Path) -> Result<(u64, String), DigestError> {
111    let before = fs::symlink_metadata(path).map_err(|_| DigestError::Unavailable)?;
112    if before.file_type().is_symlink() || !before.is_file() {
113        return Err(DigestError::NotRegularFile);
114    }
115    if before.len() == 0 {
116        return Err(DigestError::Empty);
117    }
118    let mut file = File::open(path).map_err(|_| DigestError::OpenFailed)?;
119    let (size, digest) = hash_stream(&mut file)?;
120    if size == 0 {
121        return Err(DigestError::Empty);
122    }
123    post_read_check(path, size)?;
124    Ok((size, digest))
125}
126
127/// Stream one open file through the digest, accumulating the byte count.
128fn hash_stream(file: &mut File) -> Result<(u64, String), DigestError> {
129    let mut hasher = Sha256::new();
130    let mut size = 0u64;
131    let mut buffer = [0u8; DIGEST_BUFFER_BYTES];
132    loop {
133        let count = file
134            .read(&mut buffer)
135            .map_err(|_| DigestError::ReadFailed)?;
136        if count == 0 {
137            break;
138        }
139        size = add_size(size, count as u64)?;
140        hasher.update(&buffer[..count]);
141    }
142    let digest = hasher.finalize();
143    Ok((
144        size,
145        digest.iter().map(|byte| format!("{byte:02x}")).collect(),
146    ))
147}
148
149/// Accumulate the byte count without wrapping.
150fn add_size(size: u64, count: u64) -> Result<u64, DigestError> {
151    size.checked_add(count).ok_or(DigestError::SizeOverflow)
152}
153
154/// Re-inspect the path after the read and refuse a path that changed.
155fn post_read_check(path: &Path, size: u64) -> Result<(), DigestError> {
156    let after = fs::symlink_metadata(path).map_err(|_| DigestError::ChangedDuringRead)?;
157    if !post_read_stable(&after, size) {
158        return Err(DigestError::ChangedDuringRead);
159    }
160    Ok(())
161}
162
163/// The post-read stability rule: the same kind of regular file, same length.
164fn post_read_stable(after: &fs::Metadata, size: u64) -> bool {
165    !after.file_type().is_symlink() && after.is_file() && after.len() == size
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171    use crate::test_temp_dir;
172    use std::path::PathBuf;
173
174    fn write_file(root: &Path, name: &str, bytes: &[u8]) -> PathBuf {
175        let path = root.join(name);
176        fs::write(&path, bytes).unwrap();
177        path
178    }
179
180    #[test]
181    fn regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes() {
182        let root = test_temp_dir("digest-regular");
183        let path = write_file(&root, "artifact", b"abc");
184        let (size, sha256) = file_digest(&path).unwrap();
185        assert_eq!(size, 3);
186        assert_eq!(
187            sha256,
188            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
189        );
190        assert_eq!(sha256.len(), 64);
191        assert_eq!(sha256, sha256.to_lowercase());
192        fs::remove_dir_all(root).unwrap();
193    }
194
195    #[test]
196    fn identical_bytes_digest_identically_and_different_bytes_differ() {
197        let root = test_temp_dir("digest-determinism");
198        let first = write_file(&root, "first", b"payload");
199        let second = write_file(&root, "second", b"payload");
200        let third = write_file(&root, "third", b"payload!");
201        let first_digest = file_digest(&first).unwrap();
202        let second_digest = file_digest(&second).unwrap();
203        let third_digest = file_digest(&third).unwrap();
204        assert_eq!(first_digest, second_digest);
205        assert_ne!(first_digest, third_digest);
206        assert_ne!(first_digest.0, third_digest.0);
207        fs::remove_dir_all(root).unwrap();
208    }
209
210    #[test]
211    fn empty_file_is_refused_before_it_is_read() {
212        let root = test_temp_dir("digest-empty");
213        let path = write_file(&root, "empty", b"");
214        assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
215        fs::remove_dir_all(root).unwrap();
216    }
217
218    #[test]
219    fn a_zero_length_read_is_refused_even_when_the_file_grew_empty_after_the_check() {
220        // The pre-read emptiness check observes the length *before* the read.
221        // A file truncated to nothing in between would be read as zero bytes
222        // and would otherwise pass the post-read length comparison, because
223        // the post-read length would equal the zero bytes read. A zero-length
224        // read result is refused on its own terms.
225        let root = test_temp_dir("digest-truncated");
226        let path = write_file(&root, "artifact", b"0123456789");
227        let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
228        assert_eq!(size, 10);
229        fs::write(&path, b"").unwrap();
230        assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty);
231        assert_eq!(
232            post_read_check(&path, size).unwrap_err(),
233            DigestError::ChangedDuringRead
234        );
235        fs::remove_dir_all(root).unwrap();
236    }
237
238    #[test]
239    fn directory_is_refused() {
240        let root = test_temp_dir("digest-directory");
241        assert_eq!(file_digest(&root).unwrap_err(), DigestError::NotRegularFile);
242        fs::remove_dir_all(root).unwrap();
243    }
244
245    #[test]
246    fn missing_path_is_refused() {
247        let root = test_temp_dir("digest-missing");
248        let path = root.join("absent");
249        assert_eq!(file_digest(&path).unwrap_err(), DigestError::Unavailable);
250        fs::remove_dir_all(root).unwrap();
251    }
252
253    #[cfg(unix)]
254    #[test]
255    fn symlink_is_refused() {
256        let root = test_temp_dir("digest-symlink");
257        let target = write_file(&root, "target", b"payload");
258        let link = root.join("link");
259        std::os::unix::fs::symlink(&target, &link).unwrap();
260        assert_eq!(file_digest(&link).unwrap_err(), DigestError::NotRegularFile);
261        fs::remove_dir_all(root).unwrap();
262    }
263
264    #[test]
265    fn post_read_length_change_is_refused() {
266        // The read race cannot be staged deterministically on the supported
267        // platforms: nothing guarantees that a path changes between the
268        // helper's read and its post-read re-check. The plan therefore allows
269        // asserting the post-read comparison directly instead of racing a
270        // thread, and `post_read_check` is the helper's own post-read step,
271        // exercised here on real files.
272        let root = test_temp_dir("digest-length-change");
273        let path = write_file(&root, "artifact", b"0123456789");
274        let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
275        assert_eq!(size, 10);
276        fs::write(&path, b"0123456789abcd").unwrap();
277        assert_eq!(
278            post_read_check(&path, size).unwrap_err(),
279            DigestError::ChangedDuringRead
280        );
281        fs::remove_dir_all(root).unwrap();
282    }
283
284    #[test]
285    fn post_read_type_change_is_refused() {
286        // Same deterministic-staging note as the length-change test: the
287        // helper's post-read step is asserted directly on real files.
288        let root = test_temp_dir("digest-type-change");
289        let path = write_file(&root, "artifact", b"0123456789");
290        let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
291        fs::remove_file(&path).unwrap();
292        fs::create_dir(&path).unwrap();
293        assert_eq!(
294            post_read_check(&path, size).unwrap_err(),
295            DigestError::ChangedDuringRead
296        );
297        fs::remove_dir_all(root).unwrap();
298    }
299
300    #[cfg(unix)]
301    #[test]
302    fn post_read_symlink_change_is_refused() {
303        // Same deterministic-staging note as the length-change test.
304        let root = test_temp_dir("digest-symlink-change");
305        let path = write_file(&root, "artifact", b"0123456789");
306        let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap();
307        fs::remove_file(&path).unwrap();
308        let target = write_file(&root, "target", b"0123456789");
309        std::os::unix::fs::symlink(&target, &path).unwrap();
310        assert_eq!(
311            post_read_check(&path, size).unwrap_err(),
312            DigestError::ChangedDuringRead
313        );
314        fs::remove_dir_all(root).unwrap();
315    }
316
317    #[test]
318    fn size_overflow_is_an_error_not_a_wrapped_value() {
319        assert_eq!(
320            add_size(u64::MAX, 1).unwrap_err(),
321            DigestError::SizeOverflow
322        );
323        assert_eq!(add_size(10, 5).unwrap(), 15);
324    }
325}