//! Implementation logic for `fs-mistrust`.

use std::{

    fs::{FileType, Metadata},

    path::Path,

};

#[cfg(target_family = "unix")]

use std::os::unix::prelude::MetadataExt;

use crate::{

    Error, Result, Type,

    walk::{PathType, ResolvePath},

};

/// Definition for the "sticky bit", which on Unix means that the contents of

/// directory may not be renamed, deleted, or otherwise modified by a non-owner

/// of those contents, even if the user has write permissions on the directory.

///

/// This is the usual behavior for /tmp: You can make your own directories in

/// /tmp, but you can't modify other people's.

///

/// (We'd use libc's version of `S_ISVTX`, but they vacillate between u16 and

/// u32 depending what platform you're on.)

#[cfg(target_family = "unix")]

pub(crate) const STICKY_BIT: u32 = 0o1000;

/// Helper: Box an iterator of errors.

impl<'a> super::Verifier<'a> {

    /// Return an iterator of all the security problems with `path`.

    ///

    /// If the iterator is empty, then there is no problem with `path`.

    //

    // TODO: This iterator is not fully lazy; sometimes, calls to check_one()

    // return multiple errors when it would be better for them to return only

    // one (since we're ignoring errors after the first).  This might be nice

    // to fix in the future if we can do so without adding much complexity

    // to the code.  It's not urgent, since the allocations won't cost much

    // compared to the filesystem access.

            // We don't want to walk the path in this case at all: we'll just

            // look at the last element.

            };

        };

        // Filter to remove every path that is a prefix of ignore_prefix. (IOW,

        // if stop_at_dir is /home/arachnidsGrip, real_stop_at_dir will be

        // /home, and we'll ignore / and /home.)

                // Finally, check the path for errors.

                //

                // See `check_one` below for a note on TOCTOU issues.

                    }

        )

    /// If check_contents is set, return an iterator over all the errors in

    /// elements _contained in this directory_.

    #[cfg(feature = "walkdir")]

        use std::sync::Arc;

                    },

        )

    /// Return an empty iterator.

    #[cfg(not(feature = "walkdir"))]

    pub(crate) fn check_content_errors(&self, _path: &Path) -> impl Iterator<Item = Error> + '_ {

        std::iter::empty()

    }

    /// Check a single `path` for conformance with this `Verifier`.

    ///

    /// Note that this result is only meaningful if all of the _ancestors_ of

    /// this path have been checked.  Otherwise, a non-trusted user could change

    /// where this path points after it has been checked.

    #[must_use]

        #[cfg(target_family = "unix")]

    /// Check whether a given file has the correct type, and push an error into

    /// `errors` if not. Other inputs are as for `check_one`.

            PathType::Symlink => {

                // There's nothing to check on a symlink encountered _while

                // looking up the target_; its permissions and ownership do not

                // actually matter.

            }

        };

    /// Check whether a given file has the correct ownership and permissions,

    /// and push errors into `errors` if not. Other inputs are as for

    /// `check_one`.

    ///

    /// On iOS, check permissions but assumes the owner is the current user.

    #[cfg(target_family = "unix")]

        // We need to check that the owner is trusted, since the owner can

        // always change the permissions of the object.  (If we're talking

        // about a directory, the owner cah change the permissions and owner

        // of anything in the directory.)

        #[cfg(all(

            not(target_os = "ios"),

            not(target_os = "tvos"),

            not(target_os = "android")

        ))]

        {

        }

        // On Unix-like platforms, symlink permissions are ignored (and usually

        // not settable). Theoretically, the symlink owner shouldn't matter, but

        // it's less confusing to consistently require the right owner.

            // If this is the target object, and it must not be readable, then

            // we forbid it to be group-rwx and all-rwx.

            //

            // (We allow _content_ to be globally readable even if readable_okay

            // is false, since we check that the Final directory is itself

            // unreadable.  This is okay unless the content has hard links: see

            // the Limitations section of the crate-level documentation.)

        } else {

            // If this is the target object and it may be readable, or if this

            // is _any parent directory_ or any content, then we typically

            // forbid the group-write and all-write bits.  (Those are the bits

            // that would allow non-trusted users to change the object, or

            // change things around in a directory.)

            {

                // This is an intermediate directory and this sticky bit is

                // set.  Thus, we don't care if it is world-writable or

                // group-writable, since only the _owner_  of a file in this

                // directory can move or rename it.

            } else {

                // It's not a sticky-bit intermediate directory; actually

                // forbid 022.

            }

        };

        // If we trust the GID, then we allow even more bits to be set.

        #[cfg(all(

            not(target_os = "ios"),

            not(target_os = "tvos"),

            not(target_os = "android")

        ))]

        // Both iOS and Android have some directory on the path for application data directory

        // which is group writeable. However both system already offer some guarantees regarding

        // application data being kept away from other apps.

        //

        // iOS: https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html

        // > For security purposes, an iOS app’s interactions with the file system are limited

        // to the directories inside the app’s sandbox directory

        //

        // Android: https://developer.android.com/training/data-storage

        // > App-specific storage: [...] Use the directories within internal storage to save

        // sensitive information that other apps shouldn't access.

        #[cfg(any(target_os = "ios", target_os = "tvos", target_os = "android"))]

        {

            forbidden_bits &= !0o070;

        }

}

impl super::Type {

    /// Return true if this required type is matched by a given `FileType`

    /// object.

        }

}