GitCorner

Code

ossartcraftphotocraft๐ŸŒ
856f865cf98d
//! What a replacement keeps from the file it replaces.
//!
//! Saving writes a new file and renames it over the old one, so the user gets a file with the
//! right bytes and none of the old file's history: everything the operating system and other
//! programs had attached to the file that was just unlinked is gone. Some of it is a security
//! decision โ€” *this came from the internet*, *only these people may read it* โ€” so a save that
//! drops it quietly weakens the user's protections (#6603, #7073, #7094, #7095, #7096).
//!
//! | | macOS | Linux | Windows |
//! |---|---|---|---|
//! | permission bits | [`copy_metadata`] | [`copy_metadata`] | [`copy_metadata`] (read-only flag) |
//! | extended attributes (Finder tags, `user.*`) | `copy_xattrs` | `copy_xattrs` | โ€” |
//! | "downloaded from the internet" | `com.apple.quarantine`, an xattr | โ€” | `Zone.Identifier`, a named stream kept by [`replace_existing`] |
//! | access-control list | `copy_acl` (`exacl`) | not carried over (see below) | DACL, kept by [`replace_existing`] |
//! | creation time | `copy_created` (#9388) | โ€” | kept by [`replace_existing`] |
//!
//! Everything here except [`replace_existing`] is **best effort and never touches the file's
//! bytes**: a save that cannot carry a piece of metadata across is still a save, because a
//! document the user can open matters more than a Finder tag. [`replace_existing`] *is* the
//! replacement step, so it holds the atomicity guarantee instead: it never leaves the
//! destination missing, and it falls back to a plain rename rather than fail a save.
//!
//! Not carried over, and why: Linux POSIX ACLs live in `system.posix_acl_access`, which
//! `listxattr` does not report, so copying the listed attributes misses them; they would need
//! their own step.

use std::io;
use std::path::Path;

#[cfg(unix)]
use std::os::fd::BorrowedFd;

/// Largest attribute-name list [`copy_xattrs`] will read. Names are short; a file with a
/// megabyte of them is not something a save should spend memory on.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
const MAX_XATTR_NAMES: usize = 1 << 20;

/// Largest single attribute value [`copy_xattrs`] will carry over. Finder tags and `user.*`
/// attributes are tens of bytes; a resource fork can be large, and past this it is not worth
/// holding a copy of it in memory during a save.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
const MAX_XATTR_VALUE: usize = 16 << 20;

/// First read size for an attribute list or value; grown on `ERANGE`.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
const XATTR_CHUNK: usize = 4 << 10;

/// Copy, best effort, everything [`crate::atomic::atomic_write`] should carry from the file it
/// is about to replace (`from`) onto the temporary file that will replace it (`to`).
///
/// Errors are the caller's to ignore: each piece is attempted on its own, and the first failure
/// is returned only so a caller that wants to log one can.
pub fn copy_metadata(from: &Path, to: &Path) -> io::Result<()> {
    // The group first: on Linux `chown` drops `security.capability`, so it must not follow the
    // extended-attribute copy.
    #[cfg(unix)]
    let metadata = std::fs::metadata(from);
    #[cfg(unix)]
    let group = match &metadata {
        Ok(m) => restore_group(m, to),
        Err(_) => Ok(true),
    };

    // The permission bits go on last. Writing an attribute needs the destination open for
    // writing, and replacing a read-only (0444) file would copy that mode onto the temporary
    // file and then be unable to touch it again.
    #[cfg(unix)]
    let attributes = copy_xattrs_at(from, to);
    #[cfg(not(unix))]
    let attributes = Ok(());

    // The creation time before the ACL: it needs the destination open for writing, which a
    // copied ACL denying its owner write access would refuse.
    #[cfg(target_os = "macos")]
    let created = copy_created(from, to);
    #[cfg(not(target_os = "macos"))]
    let created = Ok(());

    #[cfg(target_os = "macos")]
    let acl = copy_acl(from, to);
    #[cfg(not(target_os = "macos"))]
    let acl = Ok(());

    // A save over a 0600 file must not widen it to whatever the process default is.
    // A failed group lookup counts as "group not kept": the mode is still copied, minus the group bits.
    #[cfg(unix)]
    let permissions = metadata.and_then(|m| set_permissions_keeping_group(&m, to, group.as_ref().copied().unwrap_or(false)));
    #[cfg(not(unix))]
    let permissions = std::fs::metadata(from).and_then(|m| std::fs::set_permissions(to, m.permissions()));
    #[cfg(unix)]
    let group = group.map(drop);
    #[cfg(not(unix))]
    let group = Ok(());

    attributes.and(acl).and(created).and(group).and(permissions)
}

/// Give `to` the group of the replaced file (`from`) when it has another: group bits are access
/// for *that* group, so on a replacement owned by a different one (a setgid folder, say) they
/// would hand the file to people the original never named. `false` when the group cannot be
/// restored (the owner is not a member): [`set_permissions_keeping_group`] then leaves the group
/// bits off.
#[cfg(unix)]
fn restore_group(from: &std::fs::Metadata, to: &Path) -> io::Result<bool> {
    use std::os::unix::fs::MetadataExt;
    Ok(std::fs::metadata(to)?.gid() == from.gid() || std::os::unix::fs::chown(to, None, Some(from.gid())).is_ok())
}

/// Give `to` the permission bits of the replaced file (`from`), without the group bits when
/// [`restore_group`] could not give it the original's group.
#[cfg(unix)]
fn set_permissions_keeping_group(from: &std::fs::Metadata, to: &Path, group_kept: bool) -> io::Result<()> {
    use std::os::unix::fs::PermissionsExt;
    let mut permissions = from.permissions();
    if !group_kept {
        permissions.set_mode(permissions.mode() & !0o070);
    }
    // After the chown, which clears setuid/setgid.
    std::fs::set_permissions(to, permissions)
}

/// The creation time ("Created" in Finder) of the file being replaced, onto the file replacing
/// it: the rename leaves a new file born at the time of the save, where Photoshop keeps the
/// original's (#9388). The rename keeps the time set here.
#[cfg(target_os = "macos")]
fn copy_created(from: &Path, to: &Path) -> io::Result<()> {
    let old = std::fs::File::open(from)?;
    let new = std::fs::OpenOptions::new().write(true).open(to)?;
    copy_created_file(&old, &new)
}

/// [`copy_created`] through two open files rather than their paths, for the automation write
/// path's capability-checked handles (see [`copy_xattrs`]). `to` must be open for writing.
/// Nothing to do outside macOS: Windows keeps the time in [`replace_existing`], and Linux has no
/// settable creation time.
pub fn copy_created_file(from: &std::fs::File, to: &std::fs::File) -> io::Result<()> {
    #[cfg(target_os = "macos")]
    {
        use std::os::macos::fs::FileTimesExt;
        let created = from.metadata()?.created()?;
        to.set_times(std::fs::FileTimes::new().set_created(created))
    }
    #[cfg(not(target_os = "macos"))]
    {
        let _ = (from, to);
        Ok(())
    }
}

/// [`copy_metadata`]'s extended-attribute step, by path: open both files and hand the
/// descriptors to [`copy_xattrs`].
#[cfg(unix)]
fn copy_xattrs_at(from: &Path, to: &Path) -> io::Result<()> {
    use std::os::fd::AsFd;
    let old = std::fs::File::open(from)?;
    // Writing an attribute needs write access to the file, not only to its directory.
    let new = std::fs::OpenOptions::new().write(true).open(to)?;
    copy_xattrs(old.as_fd(), new.as_fd())
}

/// Copy every extended attribute of `from` onto `to`, best effort, through the two open files
/// rather than their paths.
///
/// Descriptors, not paths, because the automation write path holds capability-checked handles
/// and must never reach back out to an ambient path to finish a write (#7095). The same reason
/// makes this the right shape for [`copy_metadata`] too.
///
/// An attribute that cannot be read or cannot be set is skipped: `com.apple.provenance` and
/// `com.apple.rootless` on macOS and `security.*` on Linux belong to the system and refuse to
/// be written by an ordinary process, and failing a document save over one would be absurd.
/// `Err` means the attribute *list* could not be read, so nothing was copied.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
pub fn copy_xattrs(from: BorrowedFd<'_>, to: BorrowedFd<'_>) -> io::Result<()> {
    use rustix::fs::{XattrFlags, fsetxattr};

    for name in list_xattrs(from)?.split(|b| *b == 0) {
        if name.is_empty() || skip_xattr(name) {
            continue;
        }
        let Some(value) = read_xattr(from, name) else { continue };
        let _ = fsetxattr(to, name, &value, XattrFlags::empty());
    }
    Ok(())
}

/// [`copy_xattrs`] where rustix offers no extended-attribute calls (FreeBSD and the other BSDs):
/// nothing is copied, as on Windows.
#[cfg(all(unix, not(any(target_os = "linux", target_os = "android", target_vendor = "apple"))))]
pub fn copy_xattrs(_from: BorrowedFd<'_>, _to: BorrowedFd<'_>) -> io::Result<()> {
    Ok(())
}

/// Attributes that describe how the *old* file's bytes are stored rather than anything about
/// the document, and so must never be pinned onto a file holding different bytes.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
fn skip_xattr(name: &[u8]) -> bool {
    // `com.apple.decmpfs` marks a file whose data lives compressed inside the attribute itself.
    // The kernel hides it from a plain `listxattr` and refuses to set it, but a file claiming
    // compressed storage it does not have would read as garbage, so never try.
    name == b"com.apple.decmpfs"
}

/// The NUL-separated attribute names of `fd`.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
fn list_xattrs(fd: BorrowedFd<'_>) -> io::Result<Vec<u8>> {
    let mut buf = vec![0u8; XATTR_CHUNK];
    loop {
        match rustix::fs::flistxattr(fd, buf.as_mut_slice()) {
            Ok(len) => {
                buf.truncate(len.min(buf.len()));
                return Ok(buf);
            }
            Err(e) if e == rustix::io::Errno::RANGE && buf.len() < MAX_XATTR_NAMES => {
                buf.resize(buf.len().saturating_mul(4).min(MAX_XATTR_NAMES), 0);
            }
            Err(e) => return Err(e.into()),
        }
    }
}

/// The value of one attribute, or `None` if it cannot be read or is larger than
/// [`MAX_XATTR_VALUE`]. A missing value is normal: another process may remove an attribute
/// between the listing and the read.
#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
fn read_xattr(fd: BorrowedFd<'_>, name: &[u8]) -> Option<Vec<u8>> {
    let mut buf = vec![0u8; XATTR_CHUNK];
    loop {
        match rustix::fs::fgetxattr(fd, name, buf.as_mut_slice()) {
            Ok(len) => {
                buf.truncate(len.min(buf.len()));
                return Some(buf);
            }
            Err(e) if e == rustix::io::Errno::RANGE && buf.len() < MAX_XATTR_VALUE => {
                buf.resize(buf.len().saturating_mul(4).min(MAX_XATTR_VALUE), 0);
            }
            Err(_) => return None,
        }
    }
}

/// Copy an explicit macOS access-control list (`chmod +a`) from `from` onto `to` (#7073).
///
/// `fcopyfile(COPYFILE_ACL)` is the obvious call and is an `unsafe fn`, which this workspace
/// forbids; `fclonefileat` with `CLONE_ACL` is safe but only works on APFS and would mean
/// writing every save as a clone-then-truncate. `exacl` is a small, safe wrapper over
/// `acl_get_file`/`acl_set_file` that works on every file system that has ACLs at all.
///
/// An old file with no ACL leaves `to` alone: the new file may have picked up the folder's
/// inherited entries, and taking access away is a worse surprise than leaving it as the folder
/// says it should be.
#[cfg(target_os = "macos")]
fn copy_acl(from: &Path, to: &Path) -> io::Result<()> {
    let entries = exacl::getfacl(from, None)?;
    if entries.is_empty() {
        return Ok(());
    }
    exacl::setfacl(&[to], &entries, None)
}

/// Replace the **existing** file `to` with `from`, keeping what the destination owns rather than
/// its bytes.
///
/// Everywhere but Windows this is exactly [`std::fs::rename`], and the metadata is carried by
/// [`copy_metadata`] onto `from` beforehand. On Windows it is `ReplaceFileW`, which preserves
/// the replaced file's DACL (#7096), its named streams โ€” `Zone.Identifier`, the Mark of the Web
/// (#7094) โ€” its creation time, object identifier, compression and encryption, in the one call
/// Microsoft documents for the save-through-a-temporary-file pattern. None of those have a safe
/// path-based API to copy by hand.
pub fn replace_existing(from: &Path, to: &Path) -> io::Result<()> {
    #[cfg(windows)]
    {
        windows_replace(from, to)
    }
    #[cfg(not(windows))]
    {
        std::fs::rename(from, to)
    }
}

/// What the recovery ladder leaves behind after a `ReplaceFileW` answered
/// `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2` (the destination's old content now lives at the backup
/// name and the replacement still at its temporary name).
#[cfg(any(windows, test))]
#[derive(Debug)]
pub(crate) enum MoveReplacement2 {
    /// The replacement was renamed onto the destination: the save completed with its metadata.
    Completed,
    /// Completion failed but the original was put back on the destination: the save did not
    /// happen and the destination still holds the user's file. Carries the completion error.
    Restored(io::Error),
    /// Neither completion nor restoration succeeded: the original survives only at `recovery`
    /// and the destination is currently missing. The caller must report that location and must
    /// not claim an unchanged destination (#11178).
    Unresolved { completion: io::Error, restoration: io::Error, recovery: std::path::PathBuf },
}

/// The recovery ladder of [`MoveReplacement2`], kept free of the Windows call so the branch is
/// testable on every platform as branch coverage (#11178): first finish the save (`complete`,
/// the rename of the replacement onto the destination); if that fails, put the original back
/// (`restore`, the rename of the backup onto the destination).
#[cfg(any(windows, test))]
pub(crate) fn recover_after_1177(
    complete: impl FnOnce() -> io::Result<()>,
    restore: impl FnOnce() -> io::Result<()>,
    recovery: std::path::PathBuf,
) -> MoveReplacement2 {
    let Err(completion) = complete() else { return MoveReplacement2::Completed };
    match restore() {
        Ok(()) => MoveReplacement2::Restored(completion),
        Err(restoration) => MoveReplacement2::Unresolved { completion, restoration, recovery },
    }
}

/// `ReplaceFileW`, with the plain rename as the fallback. See [`replace_existing`].
///
/// **A backup name is not optional.** `ReplaceFile` without one deletes the replaced file before
/// the final rename, and documents `ERROR_UNABLE_TO_MOVE_REPLACEMENT`: "the replaced file no
/// longer exists and the replacement file exists under its original name" โ€” the user's document
/// gone, its replacement left under a temporary name. With a backup name the same failure
/// leaves both files where they were. So this always passes one, and deletes it on the way out.
///
/// The failures and what each leaves behind (from the `ReplaceFileW` reference):
///
/// - `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2` (1177) is the only one that moves anything: the
///   replacement keeps its name but has already inherited the destination's streams and
///   attributes, and the destination's old content is at the backup name. Finishing the rename
///   by hand completes the save *with* its metadata; if even that fails, the backup goes back to
///   the destination so the user's file is where they left it โ€” and if even *that* fails, the
///   error names the backup, because the original survives nowhere else (#11178).
/// - Every other error leaves the replaced and replacement files under their own names, so a
///   plain rename still saves the document โ€” without the metadata, which is where this started.
#[cfg(windows)]
fn windows_replace(from: &Path, to: &Path) -> io::Result<()> {
    use winsafe::co::REPLACEFILE;

    /// `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2`: the destination now lives under the backup name.
    const MOVE_REPLACEMENT_2: i32 = 1177;

    let backup = backup_path(to);
    let paths = (to.to_str(), from.to_str(), backup.as_deref().and_then(Path::to_str));
    // `ReplaceFileW` takes `&str`; a path that is not valid Unicode, or one past MAX_PATH, is
    // the plain rename's job.
    let (Some(replaced), Some(replacement), Some(backup_str)) = paths else {
        return std::fs::rename(from, to);
    };

    let flags = REPLACEFILE::IGNORE_MERGE_ERRORS | REPLACEFILE::IGNORE_ACL_ERRORS;
    match winsafe::ReplaceFile(replaced, replacement, Some(backup_str), flags) {
        Ok(()) => {
            remove_backup(backup.as_deref());
            Ok(())
        }
        Err(e) if e.raw() as i32 == MOVE_REPLACEMENT_2 => match backup.clone() {
            // `backup_str` came from `backup`, so it is `Some` here; if that ever changed, leave
            // the destination alone rather than guess where the original went (#11178).
            None => Err(io::Error::other(format!(
                "cannot save {}: the replacement moved the original to an unknown backup name and cannot report where",
                to.display()
            ))),
            Some(backup_path) => match recover_after_1177(|| std::fs::rename(from, to), || std::fs::rename(&backup_path, to), backup_path.clone()) {
                MoveReplacement2::Completed => {
                    remove_backup(Some(&backup_path));
                    Ok(())
                }
                // The original is back where the user left it; the completion error stands, and
                // a `PermissionDenied` one may still be retried (the temporary file is intact).
                MoveReplacement2::Restored(completion) => Err(completion),
                // Unresolved: the destination is missing and the original survives only at the
                // backup. Report the recovery location and stop the retry loop from picking a
                // fresh backup name over it (#11178).
                MoveReplacement2::Unresolved { completion, restoration, recovery } => {
                    Err(super::unresolved_recovery_error(to, &completion, &restoration, &recovery))
                }
            },
        },
        Err(_) => {
            remove_backup(backup.as_deref());
            std::fs::rename(from, to)
        }
    }
}

/// A unique name beside `to` for `ReplaceFile` to park the replaced file under. It shares the
/// temporary-file suffix, so the save's own cleanup and the tests' leftover check cover it.
#[cfg(windows)]
fn backup_path(to: &Path) -> Option<std::path::PathBuf> {
    let name = to.file_name()?.to_string_lossy().into_owned();
    let dir = match to.parent() {
        Some(d) if !d.as_os_str().is_empty() => d,
        _ => Path::new("."),
    };
    Some(dir.join(super::temp_name(&name)))
}

#[cfg(windows)]
fn remove_backup(backup: Option<&Path>) {
    if let Some(backup) = backup {
        let _ = std::fs::remove_file(backup);
    }
}

#[cfg(test)]
mod tests;