fix!: assure that special device names on Windows aren't allowed.

Otherwise it's possible to read or write to devices when interacting
with references of the 'right' name.

This behaviour can be controlled with the new `prohibit_windows_device_names` flag,
which is adjustable on the `Store` instance as field, and which now has to be
passed during instantiation as part of the new `store::init::Options` struct.

Author: Byron

gix-ref/src/lib.rs

@@ -62,6 +62,25 @@ pub mod peel;
 ///
 #[allow(clippy::empty_docs)]
 pub mod store {
+    ///
+    #[allow(clippy::empty_docs)]
+    pub mod init {
+
+        /// Options for use during [initialization](crate::Store::at).
+        #[derive(Debug, Copy, Clone, Default)]
+        pub struct Options {
+            /// How to write the ref-log.
+            pub write_reflog: super::WriteReflog,
+            /// The kind of hash to expect in
+            pub object_hash: gix_hash::Kind,
+            /// The equivalent of `core.precomposeUnicode`.
+            pub precompose_unicode: bool,
+            /// If `true`, we will avoid reading from or writing to references that contains Windows device names
+            /// to avoid side effects. This only needs to be `true` on Windows, but can be `true` on other platforms
+            /// if they need to remain compatible with Windows.
+            pub prohibit_windows_device_names: bool,
+        }
+    }
     /// The way a file store handles the reflog
     #[derive(Default, Debug, PartialOrd, PartialEq, Ord, Eq, Hash, Clone, Copy)]
     pub enum WriteReflog {
@@ -93,9 +112,8 @@ pub mod store {
     ///
     #[path = "general/handle/mod.rs"]
     mod handle;
-    pub use handle::find;
-
     use crate::file;
+    pub use handle::find;
 }
 
 /// The git reference store.

gix-ref/src/store/file/find.rs

@@ -251,7 +251,19 @@ impl file::Store {
 
     /// Read the file contents with a verified full reference path and return it in the given vector if possible.
     pub(crate) fn ref_contents(&self, name: &FullNameRef) -> io::Result<Option<Vec<u8>>> {
-        let ref_path = self.reference_path(name);
+        let (base, relative_path) = self.reference_path_with_base(name);
+        if self.prohibit_windows_device_names
+            && relative_path
+                .components()
+                .filter_map(|c| gix_path::try_os_str_into_bstr(c.as_os_str().into()).ok())
+                .any(|c| gix_validate::path::component_is_windows_device(c.as_ref()))
+        {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::Other,
+                format!("Illegal use of reserved Windows device name in \"{}\"", name.as_bstr()),
+            ));
+        }
+        let ref_path = base.join(relative_path);
 
         match std::fs::File::open(&ref_path) {
             Ok(mut file) => {

gix-ref/src/store/file/loose/mod.rs

@@ -35,22 +35,26 @@ mod init {
     impl file::Store {
         /// Create a new instance at the given `git_dir`, which commonly is a standard git repository with a
         /// `refs/` subdirectory.
-        /// The `object_hash` defines which kind of hash we should recognize.
+        /// Use [`Options`](crate::store::init::Options) to adjust settings.
         ///
-        /// Note that if `precompose_unicode` is set, the `git_dir` is also expected to use precomposed unicode,
-        /// or else some operations that strip prefixes will fail.
+        /// Note that if [`precompose_unicode`](crate::store::init::Options::precompose_unicode) is set in the options,
+        /// the `git_dir` is also expected to use precomposed unicode, or else some operations that strip prefixes will fail.
         pub fn at(
             git_dir: PathBuf,
-            write_reflog: file::WriteReflog,
-            object_hash: gix_hash::Kind,
-            precompose_unicode: bool,
+            crate::store::init::Options {
+                write_reflog,
+                object_hash,
+                precompose_unicode,
+                prohibit_windows_device_names,
+            }: crate::store::init::Options,
         ) -> Self {
             file::Store {
                 git_dir,
                 packed_buffer_mmap_threshold: packed_refs_mmap_threshold(),
                 common_dir: None,
                 write_reflog,
                 namespace: None,
+                prohibit_windows_device_names,
                 packed: gix_fs::SharedFileSnapshotMut::new().into(),
                 object_hash,
                 precompose_unicode,
@@ -60,21 +64,25 @@ mod init {
         /// Like [`at()`][file::Store::at()], but for _linked_ work-trees which use `git_dir` as private ref store and `common_dir` for
         /// shared references.
         ///
-        /// Note that if `precompose_unicode` is set, the `git_dir` and `common_dir` are also expected to use precomposed unicode,
-        /// or else some operations that strip prefixes will fail.
+        /// Note that if [`precompose_unicode`](crate::store::init::Options::precompose_unicode) is set, the `git_dir` and
+        /// `common_dir` are also expected to use precomposed unicode, or else some operations that strip prefixes will fail.
         pub fn for_linked_worktree(
             git_dir: PathBuf,
             common_dir: PathBuf,
-            write_reflog: file::WriteReflog,
-            object_hash: gix_hash::Kind,
-            precompose_unicode: bool,
+            crate::store::init::Options {
+                write_reflog,
+                object_hash,
+                precompose_unicode,
+                prohibit_windows_device_names,
+            }: crate::store::init::Options,
         ) -> Self {
             file::Store {
                 git_dir,
                 packed_buffer_mmap_threshold: packed_refs_mmap_threshold(),
                 common_dir: Some(common_dir),
                 write_reflog,
                 namespace: None,
+                prohibit_windows_device_names,
                 packed: gix_fs::SharedFileSnapshotMut::new().into(),
                 object_hash,
                 precompose_unicode,

gix-ref/src/store/file/loose/reflog/create_or_update/tests.rs

@@ -14,7 +14,13 @@ fn hex_to_id(hex: &str) -> gix_hash::ObjectId {
 
 fn empty_store(writemode: WriteReflog) -> Result<(TempDir, file::Store)> {
     let dir = TempDir::new()?;
-    let store = file::Store::at(dir.path().into(), writemode, gix_hash::Kind::Sha1, false);
+    let store = file::Store::at(
+        dir.path().into(),
+        crate::store::init::Options {
+            write_reflog: writemode,
+            ..Default::default()
+        },
+    );
     Ok((dir, store))
 }
 

gix-ref/src/store/file/mod.rs

@@ -27,6 +27,9 @@ pub struct Store {
     pub write_reflog: WriteReflog,
     /// The namespace to use for edits and reads
     pub namespace: Option<Namespace>,
+    /// This is only useful on Windows, which may have 'virtual' devices on each level of a path so that
+    /// reading or writing `refs/heads/CON` for example would read from the console, or write to it.
+    pub prohibit_windows_device_names: bool,
     /// If set, we will convert decomposed unicode like `a\u308` into precomposed unicode like `ä` when reading
     /// ref names from disk.
     /// Note that this is an internal operation that isn't observable on the outside, but it's needed for lookups

gix-ref/src/store/general/init.rs

@@ -1,7 +1,5 @@
 use std::path::PathBuf;
 
-use crate::store::WriteReflog;
-
 mod error {
     /// The error returned by [`crate::Store::at()`].
     #[derive(Debug, thiserror::Error)]
@@ -19,23 +17,16 @@ use crate::file;
 #[allow(dead_code)]
 impl crate::Store {
     /// Create a new store at the given location, typically the `.git/` directory.
+    /// Use [`opts`](crate::store::init::Options) to adjust settings.
     ///
-    /// `object_hash` defines the kind of hash to assume when dealing with refs.
-    /// `precompose_unicode` is used to set to the value of [`crate::file::Store::precompose_unicode].
-    ///
-    /// Note that if `precompose_unicode` is set, the `git_dir` is also expected to use precomposed unicode,
-    /// or else some operations that strip prefixes will fail.
-    pub fn at(
-        git_dir: PathBuf,
-        reflog_mode: WriteReflog,
-        object_hash: gix_hash::Kind,
-        precompose_unicode: bool,
-    ) -> Result<Self, Error> {
+    /// Note that if [`precompose_unicode`](crate::store::init::Options::precompose_unicode) is set in the options,
+    /// the `git_dir` is also expected to use precomposed unicode, or else some operations that strip prefixes will fail.
+    pub fn at(git_dir: PathBuf, opts: crate::store::init::Options) -> Result<Self, Error> {
         // for now, just try to read the directory - later we will do that naturally as we have to figure out if it's a ref-table or not.
         std::fs::read_dir(&git_dir)?;
         Ok(crate::Store {
             inner: crate::store::State::Loose {
-                store: file::Store::at(git_dir, reflog_mode, object_hash, precompose_unicode),
+                store: file::Store::at(git_dir, opts),
             },
         })
     }

gix-ref/tests/file/mod.rs

@@ -15,26 +15,13 @@ pub fn store_with_packed_refs() -> crate::Result<Store> {
 
 pub fn store_at(name: &str) -> crate::Result<Store> {
     let path = gix_testtools::scripted_fixture_read_only_standalone(name)?;
-    Ok(Store::at(
-        path.join(".git"),
-        gix_ref::store::WriteReflog::Normal,
-        gix_hash::Kind::Sha1,
-        false,
-    ))
+    Ok(Store::at(path.join(".git"), Default::default()))
 }
 
 fn store_writable(name: &str) -> crate::Result<(gix_testtools::tempfile::TempDir, Store)> {
     let dir = gix_testtools::scripted_fixture_writable_standalone(name)?;
     let git_dir = dir.path().join(".git");
-    Ok((
-        dir,
-        Store::at(
-            git_dir,
-            gix_ref::store::WriteReflog::Normal,
-            gix_hash::Kind::Sha1,
-            false,
-        ),
-    ))
+    Ok((dir, Store::at(git_dir, Default::default())))
 }
 
 struct EmptyCommit;

gix-ref/tests/file/store/mod.rs

@@ -21,9 +21,11 @@ fn precompose_unicode_journey() -> crate::Result {
 
     let store_decomposed = gix_ref::file::Store::at(
         root,
-        WriteReflog::Always,
-        gix_hash::Kind::Sha1,
-        false, /* precompose_unicode */
+        gix_ref::store::init::Options {
+            write_reflog: WriteReflog::Always,
+            precompose_unicode: false,
+            ..Default::default()
+        },
     );
     assert!(!store_decomposed.precompose_unicode);
 
@@ -46,9 +48,11 @@ fn precompose_unicode_journey() -> crate::Result {
 
     let store_precomposed = gix_ref::file::Store::at(
         tmp.path().join(precomposed_a), // it's important that root paths are also precomposed then.
-        WriteReflog::Always,
-        gix_hash::Kind::Sha1,
-        true, /* precompose_unicode */
+        gix_ref::store::init::Options {
+            write_reflog: WriteReflog::Always,
+            precompose_unicode: true,
+            ..Default::default()
+        },
     );
 
     let precomposed_ref = format!("refs/heads/{precomposed_a}");

gix-ref/tests/file/store/reflog.rs

@@ -1,9 +1,10 @@
 fn store() -> crate::Result<crate::file::Store> {
     Ok(crate::file::Store::at(
         gix_testtools::scripted_fixture_read_only_standalone("make_repo_for_reflog.sh")?.join(".git"),
-        gix_ref::store::WriteReflog::Disable,
-        gix_hash::Kind::Sha1,
-        false,
+        gix_ref::store::init::Options {
+            write_reflog: gix_ref::store::WriteReflog::Disable,
+            ..Default::default()
+        },
     ))
 }
 

gix-ref/tests/file/transaction/mod.rs

@@ -22,12 +22,7 @@ pub(crate) mod prepare_and_commit {
 
     pub(crate) fn empty_store() -> crate::Result<(gix_testtools::tempfile::TempDir, file::Store)> {
         let dir = gix_testtools::tempfile::TempDir::new().unwrap();
-        let store = file::Store::at(
-            dir.path().into(),
-            gix_ref::store::WriteReflog::Normal,
-            gix_hash::Kind::Sha1,
-            false,
-        );
+        let store = file::Store::at(dir.path().into(), Default::default());
         Ok((dir, store))
     }
 

gix-ref/tests/file/transaction/prepare_and_commit/create_or_update/mod.rs

@@ -10,6 +10,7 @@ use gix_ref::{
     transaction::{Change, LogChange, PreviousValue, RefEdit, RefLog},
     Target,
 };
+use std::error::Error;
 
 use crate::{
     file::{
@@ -430,6 +431,63 @@ fn symbolic_reference_writes_reflog_if_previous_value_is_set() -> crate::Result
     Ok(())
 }
 
+#[test]
+fn windows_device_name_is_illegal_with_enabled_windows_protections() -> crate::Result {
+    let (_keep, mut store) = empty_store()?;
+    store.prohibit_windows_device_names = true;
+    let log_ignored = LogChange {
+        mode: RefLog::AndReference,
+        force_create_reflog: false,
+        message: "ignored".into(),
+    };
+
+    let new = Target::Peeled(hex_to_id("28ce6a8b26aa170e1de65536fe8abe1832bd3242"));
+    for invalid_name in ["refs/heads/CON", "refs/CON/still-invalid"] {
+        let err = store
+            .transaction()
+            .prepare(
+                Some(RefEdit {
+                    change: Change::Update {
+                        log: log_ignored.clone(),
+                        new: new.clone(),
+                        expected: PreviousValue::Any,
+                    },
+                    name: invalid_name.try_into()?,
+                    deref: false,
+                }),
+                Fail::Immediately,
+                Fail::Immediately,
+            )
+            .unwrap_err();
+        assert_eq!(
+            err.source().expect("inner").to_string(),
+            format!("Illegal use of reserved Windows device name in \"{invalid_name}\""),
+            "it's notable that the check also kicks in when the previous value doesn't matter - we expect a 'read' to happen anyway \
+            - it can't be optimized away as the previous value is stored in the transaction result right now."
+        );
+    }
+
+    #[cfg(not(windows))]
+    {
+        store.prohibit_windows_device_names = false;
+        let _prepared_transaction = store.transaction().prepare(
+            Some(RefEdit {
+                change: Change::Update {
+                    log: log_ignored.clone(),
+                    new,
+                    expected: PreviousValue::Any,
+                },
+                name: "refs/heads/CON".try_into()?,
+                deref: false,
+            }),
+            Fail::Immediately,
+            Fail::Immediately,
+        )?;
+    }
+
+    Ok(())
+}
+
 #[test]
 fn symbolic_head_missing_referent_then_update_referent() -> crate::Result {
     for reflog_writemode in &[WriteReflog::Normal, WriteReflog::Disable, WriteReflog::Always] {

gix-ref/tests/file/worktree.rs

@@ -29,7 +29,7 @@ fn main_store(
     let (dir, tmp) = dir(packed, writable)?;
     let git_dir = dir.join("repo").join(".git");
     Ok((
-        gix_ref::file::Store::at(git_dir.clone(), Default::default(), Default::default(), false),
+        gix_ref::file::Store::at(git_dir.clone(), Default::default()),
         gix_odb::at(git_dir.join("objects"))?,
         tmp,
     ))
@@ -50,13 +50,7 @@ fn worktree_store(
         .into_repository_and_work_tree_directories();
     let common_dir = git_dir.join("../..");
     Ok((
-        gix_ref::file::Store::for_linked_worktree(
-            git_dir,
-            common_dir.clone(),
-            Default::default(),
-            Default::default(),
-            false,
-        ),
+        gix_ref::file::Store::for_linked_worktree(git_dir, common_dir.clone(), Default::default()),
         gix_odb::at(common_dir.join("objects"))?,
         tmp,
     ))