supreme_hook_config/

dir_listing.rs

//! Pure logic supporting `hooks::query_dir`'s directory-listing hook: buffer
//! rewriting, plus the glob-style filename matching used to decide which
//! mod-provided files belong in a given listing.
//!
//! This used to live entirely as raw-pointer arithmetic directly inside
//! `hooks::query_dir`'s detour closure, the riskiest `unsafe` code in the
//! proxy crate (walking and mutating an OS-owned, variable-length-record
//! buffer) and, until now, the least testable, since it only ever existed
//! as a `*mut u8` live during an actual `NtQueryDirectoryFile` call.
//!
//! Everything here instead takes plain, owned/borrowed values, a
//! `&mut [u8]` for the buffer functions, `&str` for the matcher, and uses
//! ordinary slice indexing: an out-of-bounds access panics loudly instead
//! of corrupting memory silently, and the whole thing can be exercised
//! against a hand-built buffer in a plain `#[test]`, with no OS, no
//! Windows target, and no running game involved. `hooks::query_dir`'s
//! detour is now a thin `unsafe` wrapper that builds a `&mut [u8]` view of
//! the real syscall buffer via
//! `slice::from_raw_parts_mut(file_information as *mut u8, length as usize)`
//! and hands it to the functions below, the `unsafe` is now confined to
//! that one slice construction instead of spread across every field access.

/// Byte offsets of the three fields every supported `FileXxxInformation`
/// variant has, relative to the start of one directory-listing entry.
/// `hooks::query_dir::get_dir_info_offsets` derives these (via
/// `offset_of!` on the real struct layouts) and passes them in here; this
/// module doesn't know about any specific info class, only these offsets.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct EntryOffsets {
    pub next_entry_offset: usize,
    pub file_name_length: usize,
    pub file_name: usize,
}

fn read_u32(buf: &[u8], pos: usize) -> u32 {
    u32::from_ne_bytes(buf[pos..pos + 4].try_into().unwrap())
}

fn write_u32(buf: &mut [u8], pos: usize, value: u32) {
    buf[pos..pos + 4].copy_from_slice(&value.to_ne_bytes());
}

/// Result of [`filter_redirected_entries`].
#[derive(Debug, PartialEq, Eq)]
pub struct FilterResult {
    /// Total bytes occupied by the retained entries, starting at `buf[0]`.
    pub bytes_written: usize,
    /// Byte offset of the last retained entry's header, if any. Callers
    /// that want to append more entries after filtering (e.g. injecting
    /// mod-only entries via [`write_directory_entry`]) pass this as that
    /// function's `prev_entry_offset` to keep the chain intact.
    pub last_entry_offset: Option<usize>,
}

/// Compacts `buf[..valid_len]` in place: entries are `FileXxxInformation`-
/// shaped records chained by `NextEntryOffset`, and any entry whose
/// rel_key (`rel_dir/name`, or bare `name` when `rel_dir` is empty,
/// lowercased) makes `is_redirected` return `true` is dropped. Retained
/// entries are copied down to close the resulting gap and rechained.
///
/// Traversal rules mirror the original raw-pointer loop this replaces,
/// with one deliberate correctness fix: see the comment at the
/// `entry_name_len` bounds check below. Everything else, including
/// trusting `NextEntryOffset == 0` to mean "last entry", the same contract
/// the real syscall's output follows, is unchanged.
pub fn filter_redirected_entries(
    buf: &mut [u8],
    valid_len: usize,
    offsets: EntryOffsets,
    rel_dir: &str,
    mut is_redirected: impl FnMut(&str) -> bool,
) -> FilterResult {
    let mut read_pos = 0usize;
    let mut write_pos = 0usize;
    let mut last_entry_offset: Option<usize> = None;

    loop {
        if read_pos + offsets.file_name_length + 4 > valid_len {
            break;
        }
        let next_offset = read_u32(buf, read_pos + offsets.next_entry_offset) as usize;
        let entry_name_len = read_u32(buf, read_pos + offsets.file_name_length) as usize;

        // The original check here was `offsets.file_name + entry_name_len
        // > valid_len`, bounding entry_name_len against the *total*
        // buffer length rather than the space actually remaining from
        // read_pos. That's the right check for the very first entry
        // (where read_pos == 0) but not for any entry after it: a
        // corrupt/oversized entry_name_len deep in the buffer could pass
        // that check while still describing a name that runs past
        // valid_len, and the read below would go out of bounds. Bounding
        // against the remaining space from read_pos is what the check was
        // actually trying to express, see the
        // `filter_stops_at_a_truncated_final_entry_instead_of_reading_out_of_bounds`
        // test for the case this fixes.
        if read_pos + offsets.file_name + entry_name_len > valid_len {
            break;
        }

        let entry_size = if next_offset > 0 {
            next_offset
        } else {
            (offsets.file_name + entry_name_len + 7) & !7
        };

        let name_pos = read_pos + offsets.file_name;
        let name_u16: Vec<u16> = buf[name_pos..name_pos + entry_name_len]
            .as_chunks::<2>()
            .0
            .iter()
            .map(|pair| u16::from_ne_bytes(*pair))
            .collect();
        let name = String::from_utf16_lossy(&name_u16).to_lowercase();

        let rel_key = if rel_dir.is_empty() {
            name
        } else {
            format!("{rel_dir}/{name}")
        };

        if !is_redirected(&rel_key) {
            if write_pos != read_pos {
                buf.copy_within(read_pos..read_pos + entry_size, write_pos);
            }
            if let Some(prev) = last_entry_offset {
                write_u32(
                    buf,
                    prev + offsets.next_entry_offset,
                    (write_pos - prev) as u32,
                );
            }
            last_entry_offset = Some(write_pos);
            write_pos += entry_size;
        }

        if next_offset == 0 {
            break;
        }
        if read_pos + next_offset >= valid_len {
            break;
        }
        read_pos += next_offset;
    }

    if let Some(prev) = last_entry_offset {
        write_u32(buf, prev + offsets.next_entry_offset, 0);
    }

    FilterResult {
        bytes_written: write_pos,
        last_entry_offset,
    }
}

/// Writes one synthetic directory entry (an injected mod-only filename) at
/// `buf[pos..]`, matching the layout the original inline code built:
/// zeroed header, `NextEntryOffset` left at 0 (patched later, on the
/// *previous* entry, once this one is known to exist, see
/// `prev_entry_offset` below), `FileAttributes` set to
/// `FILE_ATTRIBUTE_NORMAL` when this info class has that field
/// (`offsets.file_name >= 60` mirrors the original's `name_off >= 60`
/// check, every supported class with a `file_name` offset that high also
/// has `file_attributes` at byte 56), `FileNameLength`, and the name
/// itself.
///
/// If `prev_entry_offset` is `Some`, that earlier entry's
/// `NextEntryOffset` is patched to point at this one, the equivalent of
/// the original loop's `prev_entry_ptr` bookkeeping.
///
/// Returns `None` (writing nothing) if the entry wouldn't fit in
/// `buf[pos..]`, matching the original's `if write_ptr + entry_size >
/// buf_end { break; }` check, callers should stop injecting further
/// entries when this returns `None`, same as the original loop did.
pub fn write_directory_entry(
    buf: &mut [u8],
    pos: usize,
    offsets: EntryOffsets,
    name: &str,
    prev_entry_offset: Option<usize>,
) -> Option<usize> {
    const FILE_ATTRIBUTE_NORMAL: u32 = 0x0000_0080;

    let wide_name: Vec<u16> = name.encode_utf16().collect();
    let name_bytes = wide_name.len() * 2;
    let entry_size = (offsets.file_name + name_bytes + 7) & !7;

    if pos + entry_size > buf.len() {
        return None;
    }

    buf[pos..pos + entry_size].fill(0);
    write_u32(buf, pos + offsets.next_entry_offset, 0);
    if offsets.file_name >= 60 {
        write_u32(buf, pos + 56, FILE_ATTRIBUTE_NORMAL);
    }
    write_u32(buf, pos + offsets.file_name_length, name_bytes as u32);

    let name_pos = pos + offsets.file_name;
    for (i, unit) in wide_name.iter().enumerate() {
        buf[name_pos + i * 2..name_pos + i * 2 + 2].copy_from_slice(&unit.to_ne_bytes());
    }

    if let Some(prev) = prev_entry_offset {
        write_u32(buf, prev + offsets.next_entry_offset, (pos - prev) as u32);
    }

    Some(entry_size)
}

/// Glob-style filename matcher supporting `*` (any run of characters,
/// including none) and `?` (exactly one character), via a straightforward
/// O(n·m) dynamic-programming table over the two strings' characters.
///
/// Case-sensitive by itself, `hooks::query_dir`'s hook lowercases both the
/// candidate name and the pattern before calling this, and any other
/// caller wanting case-insensitive matching is responsible for doing the
/// same; see `is_case_sensitive_by_itself` below.
pub fn wildcard_match(name: &str, pattern: &str) -> bool {
    let n: Vec<char> = name.chars().collect();
    let p: Vec<char> = pattern.chars().collect();
    let mut dp = vec![vec![false; p.len() + 1]; n.len() + 1];
    dp[0][0] = true;
    for j in 1..=p.len() {
        if p[j - 1] == '*' {
            dp[0][j] = dp[0][j - 1];
        }
    }
    for i in 1..=n.len() {
        for j in 1..=p.len() {
            dp[i][j] = if p[j - 1] == '*' {
                dp[i - 1][j] || dp[i][j - 1]
            } else if p[j - 1] == '?' || p[j - 1] == n[i - 1] {
                dp[i - 1][j - 1]
            } else {
                false
            };
        }
    }
    dp[n.len()][p.len()]
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `FileNamesInformation`-shaped offsets: NextEntryOffset @ 0,
    /// FileIndex @ 4, FileNameLength @ 8, FileName @ 12. The smallest of
    /// the supported info classes, and enough to exercise both functions
    /// above without needing the larger structs' irrelevant padding.
    const NAMES_OFFSETS: EntryOffsets = EntryOffsets {
        next_entry_offset: 0,
        file_name_length: 8,
        file_name: 12,
    };

    /// Builds a `FileNamesInformation`-shaped buffer out of `names`,
    /// chained via `NextEntryOffset` the same way the real syscall would,
    /// with the last entry's `NextEntryOffset` left at 0.
    fn build_names_buffer(names: &[&str]) -> Vec<u8> {
        let mut buf = Vec::new();
        let mut entry_starts = Vec::new();
        for name in names {
            entry_starts.push(buf.len());
            let wide: Vec<u16> = name.encode_utf16().collect();
            let name_bytes = wide.len() * 2;
            let entry_size = (NAMES_OFFSETS.file_name + name_bytes + 7) & !7;
            let mut entry = vec![0u8; entry_size];
            entry[8..12].copy_from_slice(&(name_bytes as u32).to_ne_bytes());
            for (i, unit) in wide.iter().enumerate() {
                entry[12 + i * 2..12 + i * 2 + 2].copy_from_slice(&unit.to_ne_bytes());
            }
            buf.extend_from_slice(&entry);
        }
        for i in 0..entry_starts.len() {
            let next = if i + 1 < entry_starts.len() {
                (entry_starts[i + 1] - entry_starts[i]) as u32
            } else {
                0
            };
            buf[entry_starts[i]..entry_starts[i] + 4].copy_from_slice(&next.to_ne_bytes());
        }
        buf
    }

    /// Test-only helper mirroring how a caller reads back a buffer's
    /// entries, for asserting on results.
    fn read_all_names(buf: &[u8], valid_len: usize, offsets: EntryOffsets) -> Vec<String> {
        let mut names = Vec::new();
        let mut pos = 0;
        loop {
            if pos + offsets.file_name_length + 4 > valid_len {
                break;
            }
            let next = read_u32(buf, pos + offsets.next_entry_offset) as usize;
            let name_len = read_u32(buf, pos + offsets.file_name_length) as usize;
            let name_pos = pos + offsets.file_name;
            let wide: Vec<u16> = buf[name_pos..name_pos + name_len]
                .as_chunks::<2>()
                .0
                .iter()
                .map(|pair| u16::from_ne_bytes(*pair))
                .collect();
            names.push(String::from_utf16_lossy(&wide));
            if next == 0 {
                break;
            }
            pos += next;
        }
        names
    }

    // --- filter_redirected_entries ---

    #[test]
    fn filter_keeps_all_entries_when_nothing_is_redirected() {
        let mut buf = build_names_buffer(&["save1.dat", "save2.dat", "save3.dat"]);
        let valid_len = buf.len();
        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |_| false);
        assert_eq!(result.bytes_written, valid_len);
        assert_eq!(
            read_all_names(&buf, result.bytes_written, NAMES_OFFSETS),
            vec!["save1.dat", "save2.dat", "save3.dat"]
        );
    }

    #[test]
    fn filter_drops_a_middle_entry_and_rechains_around_it() {
        let mut buf = build_names_buffer(&["keep1.dat", "drop.dat", "keep2.dat"]);
        let valid_len = buf.len();
        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |name| {
            name == "drop.dat"
        });
        assert_eq!(
            read_all_names(&buf, result.bytes_written, NAMES_OFFSETS),
            vec!["keep1.dat", "keep2.dat"]
        );
    }

    #[test]
    fn filter_drops_the_first_entry() {
        let mut buf = build_names_buffer(&["drop.dat", "keep.dat"]);
        let valid_len = buf.len();
        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |name| {
            name == "drop.dat"
        });
        assert_eq!(
            read_all_names(&buf, result.bytes_written, NAMES_OFFSETS),
            vec!["keep.dat"]
        );
    }

    #[test]
    fn filter_drops_the_last_entry_and_renulls_the_new_last_next_offset() {
        let mut buf = build_names_buffer(&["keep.dat", "drop.dat"]);
        let valid_len = buf.len();
        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |name| {
            name == "drop.dat"
        });
        assert_eq!(
            read_all_names(&buf, result.bytes_written, NAMES_OFFSETS),
            vec!["keep.dat"]
        );
        // "keep.dat" is now the last surviving entry; its NextEntryOffset
        // must be re-nulled even though it wasn't 0 in the original buffer
        // (it originally pointed at "drop.dat").
        let last = result.last_entry_offset.unwrap();
        assert_eq!(read_u32(&buf, last + NAMES_OFFSETS.next_entry_offset), 0);
    }

    #[test]
    fn filter_drops_everything() {
        let mut buf = build_names_buffer(&["drop1.dat", "drop2.dat"]);
        let valid_len = buf.len();
        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |_| true);
        assert_eq!(result.bytes_written, 0);
        assert_eq!(result.last_entry_offset, None);
    }

    #[test]
    fn filter_passes_lowercased_rel_dir_prefixed_key_to_the_predicate() {
        let mut buf = build_names_buffer(&["Save1.DAT"]);
        let valid_len = buf.len();
        let mut seen = None;
        filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "data/saves", |key| {
            seen = Some(key.to_string());
            false
        });
        assert_eq!(seen.as_deref(), Some("data/saves/save1.dat"));
    }

    #[test]
    fn filter_with_empty_rel_dir_uses_bare_lowercased_name_as_key() {
        let mut buf = build_names_buffer(&["Save1.DAT"]);
        let valid_len = buf.len();
        let mut seen = None;
        filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |key| {
            seen = Some(key.to_string());
            false
        });
        assert_eq!(seen.as_deref(), Some("save1.dat"));
    }

    #[test]
    fn filter_stops_at_a_truncated_final_entry_instead_of_reading_out_of_bounds() {
        // A buffer whose second entry claims a FileNameLength longer than
        // the space actually left in it. With the fixed bounds check (see
        // the comment in filter_redirected_entries), the scan stops before
        // that entry instead of indexing past valid_len.
        let mut buf = build_names_buffer(&["ok.dat"]);
        let ok_entry_size = buf.len();

        // Append a second entry header claiming a huge file_name_length,
        // with no actual name bytes behind it.
        buf.extend_from_slice(&0u32.to_ne_bytes()); // next_entry_offset
        buf.extend_from_slice(&0u32.to_ne_bytes()); // file_index
        buf.extend_from_slice(&1000u32.to_ne_bytes()); // file_name_length (bogus)
        let valid_len = buf.len(); // far short of 1000 bytes of name data

        // Chain the first entry into the truncated second one
        // (build_names_buffer left NextEntryOffset at 0 since "ok.dat" was
        // the only name originally passed in).
        buf[0..4].copy_from_slice(&(ok_entry_size as u32).to_ne_bytes());

        let result = filter_redirected_entries(&mut buf, valid_len, NAMES_OFFSETS, "", |_| false);
        assert_eq!(
            read_all_names(&buf, result.bytes_written, NAMES_OFFSETS),
            vec!["ok.dat"]
        );
    }

    // --- write_directory_entry ---

    #[test]
    fn write_directory_entry_writes_name_and_length() {
        let mut buf = vec![0u8; 64];
        let written = write_directory_entry(&mut buf, 0, NAMES_OFFSETS, "mod.dat", None);
        assert!(written.is_some());
        let name_len = read_u32(&buf, NAMES_OFFSETS.file_name_length) as usize;
        assert_eq!(name_len, "mod.dat".encode_utf16().count() * 2);
        assert_eq!(read_all_names(&buf, buf.len(), NAMES_OFFSETS)[0], "mod.dat");
    }

    #[test]
    fn write_directory_entry_chains_previous_entrys_next_offset() {
        let mut buf = vec![0u8; 128];
        let first_size =
            write_directory_entry(&mut buf, 0, NAMES_OFFSETS, "first.dat", None).unwrap();
        write_directory_entry(&mut buf, first_size, NAMES_OFFSETS, "second.dat", Some(0));

        assert_eq!(
            read_all_names(&buf, buf.len(), NAMES_OFFSETS),
            vec!["first.dat", "second.dat"]
        );
    }

    #[test]
    fn write_directory_entry_returns_none_when_it_would_not_fit() {
        let mut buf = vec![0u8; 16]; // too small for the header plus any name
        let written = write_directory_entry(&mut buf, 0, NAMES_OFFSETS, "toolong.dat", None);
        assert_eq!(written, None);
    }

    #[test]
    fn write_directory_entry_sets_file_attribute_normal_when_offset_supports_it() {
        // FileDirectoryInformation-shaped offsets: file_attributes @ 56,
        // file_name_length @ 60, file_name @ 64 -- matches
        // hooks::query_dir::FILE_DIRECTORY_INFO_OFFSETS.
        let dir_offsets = EntryOffsets {
            next_entry_offset: 0,
            file_name_length: 60,
            file_name: 64,
        };
        let mut buf = vec![0u8; 128];
        write_directory_entry(&mut buf, 0, dir_offsets, "mod.dat", None);
        assert_eq!(read_u32(&buf, 56), 0x0000_0080); // FILE_ATTRIBUTE_NORMAL
    }

    #[test]
    fn write_directory_entry_skips_file_attribute_write_for_small_headers() {
        // FileNamesInformation has no FileAttributes field, and byte 56 is
        // out of bounds for this 32-byte buffer entirely -- the
        // `offsets.file_name >= 60` guard must skip that write rather than
        // panic on an out-of-bounds index or corrupt an unrelated field.
        let mut buf = vec![0xAAu8; 32];
        write_directory_entry(&mut buf, 0, NAMES_OFFSETS, "x.dat", None);
        let name_len = read_u32(&buf, NAMES_OFFSETS.file_name_length) as usize;
        assert_eq!(name_len, "x.dat".encode_utf16().count() * 2);
    }
}

#[cfg(test)]
mod wildcard_match_tests {
    use super::wildcard_match;

    #[test]
    fn exact_match() {
        assert!(wildcard_match("save.dat", "save.dat"));
    }

    #[test]
    fn no_match_different_name() {
        assert!(!wildcard_match("save.dat", "config.dat"));
    }

    #[test]
    fn star_matches_everything() {
        assert!(wildcard_match("save.dat", "*"));
        assert!(wildcard_match("", "*"));
    }

    #[test]
    fn star_matches_suffix() {
        assert!(wildcard_match("save.dat", "*.dat"));
        assert!(!wildcard_match("save.txt", "*.dat"));
    }

    #[test]
    fn star_matches_prefix() {
        assert!(wildcard_match("save1.dat", "save*"));
        assert!(!wildcard_match("config.dat", "save*"));
    }

    #[test]
    fn star_matches_middle() {
        assert!(wildcard_match("save_001_final.dat", "save*final.dat"));
    }

    #[test]
    fn star_can_match_empty_string() {
        assert!(wildcard_match("save.dat", "save*.dat"));
    }

    #[test]
    fn question_mark_matches_exactly_one_char() {
        assert!(wildcard_match("save1.dat", "save?.dat"));
        assert!(!wildcard_match("save12.dat", "save?.dat"));
        assert!(!wildcard_match("save.dat", "save?.dat"));
    }

    #[test]
    fn multiple_stars() {
        assert!(wildcard_match(
            "save_001_backup_final.dat",
            "save*backup*.dat"
        ));
    }

    #[test]
    fn empty_pattern_only_matches_empty_name() {
        assert!(wildcard_match("", ""));
        assert!(!wildcard_match("save.dat", ""));
    }

    #[test]
    fn empty_name_matches_only_all_star_pattern() {
        assert!(wildcard_match("", "***"));
        assert!(!wildcard_match("", "save*"));
    }

    // wildcard_match itself is case-sensitive; callers are responsible for
    // lowercasing both sides first (as query_dir.rs's hook does via
    // to_lowercase() before ever calling this). Documenting that contract
    // here as a test, since a future call site that forgets to lowercase
    // would fail silently (no match, not a panic) rather than loudly.
    #[test]
    fn is_case_sensitive_by_itself() {
        assert!(!wildcard_match("Save.dat", "save.dat"));
    }
}