ic_backup/ops/artifacts/
mod.rs

1//! Stream artifact bytes through descriptor-based no-follow traversal.
2
3#[cfg(test)]
4mod regressions;
5mod secure;
6#[cfg(test)]
7mod tests;
8
9use crate::model::artifacts::ArtifactChecksumRecord;
10use sha2::{Digest, Sha256};
11#[cfg(unix)]
12use std::io::Write;
13use std::{
14    io::{self, Read},
15    path::{Path, PathBuf},
16};
17use thiserror::Error;
18
19/// Checksum one regular filesystem file without following path symlinks.
20///
21/// # Errors
22/// Rejects unsafe entry types, unsupported platforms and filesystem failures.
23pub fn checksum_file(path: &Path) -> Result<ArtifactChecksumRecord, ArtifactError> {
24    secure::checksum_path(path, secure::ExpectedArtifactType::File)
25}
26
27/// Checksum one file or a deterministic directory listing.
28///
29/// # Errors
30/// Rejects unsafe entry types, unsupported platforms and filesystem failures.
31pub fn checksum_path(path: &Path) -> Result<ArtifactChecksumRecord, ArtifactError> {
32    secure::checksum_path(path, secure::ExpectedArtifactType::Any)
33}
34
35/// Checksum a directory using sorted relative-path/file-digest pairs.
36///
37/// # Errors
38/// Rejects unsafe entry types, unsupported platforms and filesystem failures.
39pub fn checksum_directory(path: &Path) -> Result<ArtifactChecksumRecord, ArtifactError> {
40    secure::checksum_path(path, secure::ExpectedArtifactType::Directory)
41}
42
43/// Stream an already-open reader using a bounded transfer buffer.
44///
45/// Interrupted reads retry internally. The caller owns blocking and timeouts;
46/// no network or paid-operation retry is performed.
47///
48/// # Errors
49/// Returns other reader IO failures unchanged; impossible byte counts reject as
50/// [`io::ErrorKind::InvalidData`] rather than indexing outside the transfer buffer.
51pub fn checksum_reader(reader: &mut impl Read) -> Result<ArtifactChecksumRecord, ArtifactError> {
52    let identity =
53        ic_host_artifacts::artifact::hash_reader(reader, u64::MAX).map_err(io::Error::from)?;
54    Ok(ArtifactChecksumRecord::from_digest(
55        *identity.sha256.as_bytes(),
56    ))
57}
58
59#[cfg(unix)]
60pub(crate) fn copy_from_reader(
61    reader: &mut impl Read,
62    writer: &mut impl Write,
63) -> Result<ArtifactChecksumRecord, ArtifactError> {
64    use ic_host_artifacts::artifact::CopyError;
65
66    // Artifacts have no total-size ceiling here. Descriptor admission, private
67    // staging, retained checksum comparison and publication remain local.
68    let identity =
69        ic_host_artifacts::artifact::copy_reader(reader, writer, u64::MAX).map_err(|error| {
70            match error {
71                CopyError::Input(error) => ArtifactError::Io(error.into()),
72                CopyError::Output(error) => ArtifactError::Io(error),
73            }
74        })?;
75    Ok(ArtifactChecksumRecord::from_digest(
76        *identity.sha256.as_bytes(),
77    ))
78}
79
80pub(crate) fn checksum_relative_files(
81    mut files: Vec<(PathBuf, ArtifactChecksumRecord)>,
82) -> ArtifactChecksumRecord {
83    files.sort_by(|left, right| left.0.cmp(&right.0));
84    let mut hasher = Sha256::new();
85    for (relative, checksum) in files {
86        hasher.update(relative.to_string_lossy().as_bytes());
87        hasher.update([0]);
88        hasher.update(checksum.hash().as_bytes());
89        hasher.update(*b"\n");
90    }
91    ArtifactChecksumRecord::from_digest(hasher.finalize().into())
92}
93
94#[cfg(unix)]
95fn require_utf8_tree_name(
96    name: &std::ffi::OsStr,
97    display_root: &Path,
98) -> Result<(), ArtifactError> {
99    if name.to_str().is_none() {
100        return Err(ArtifactError::NonUtf8Path {
101            path: display_root.join(name),
102        });
103    }
104    Ok(())
105}
106
107/// Checksum a normal relative path beneath an operator-selected root.
108///
109/// # Errors
110/// Rejects traversal, symlinks, special entries and IO failures.
111pub fn checksum_relative_path(
112    root: &Path,
113    relative: &Path,
114) -> Result<ArtifactChecksumRecord, ArtifactError> {
115    secure::checksum_relative_path(root, relative)
116}
117
118/// Stage exact source bytes in a new private file or directory and checksum them.
119///
120/// The caller owns a trusted destination parent. This copy is not durable
121/// publication; use the persistence operation after verifying its digest.
122///
123/// # Errors
124/// Rejects source traversal/symlinks, existing destinations and IO failures.
125pub fn stage_relative_path(
126    root: &Path,
127    relative: &Path,
128    destination: &Path,
129) -> Result<ArtifactChecksumRecord, ArtifactError> {
130    secure::stage_relative_path(root, relative, destination)
131}
132
133/// Typed artifact traversal or IO failure.
134#[derive(Debug, Error)]
135pub enum ArtifactError {
136    /// A path cannot be represented exactly in the maintained UTF-8 tree digest.
137    #[error("artifact path is not UTF-8: {path:?}")]
138    NonUtf8Path {
139        /// Exact rejected filesystem path.
140        path: PathBuf,
141    },
142    /// A filesystem operation or stream failed.
143    #[error(transparent)]
144    Io(#[from] io::Error),
145    /// A tree entry is neither a regular file nor a directory.
146    #[error("unsupported artifact entry at {path}: {kind}")]
147    UnsupportedEntry {
148        /// Entry path for diagnostics.
149        path: String,
150        /// Observed filesystem entry kind.
151        kind: String,
152    },
153    /// Secure descriptor traversal is unavailable on this host.
154    #[error("secure artifact traversal is unsupported on platform {0}")]
155    UnsupportedPlatform(&'static str),
156}
ic_backup/ops/artifacts/mod.rs

ic_backup/ops/artifacts/
mod.rs
