dengel / dengel-git

Public
Star on GitHubFork on GitHub
Clone

git clone https://git.dengel.dev/dengel/dengel-git.git

Commit bb7110d
//! G3 validation gate (NMA-1452): refname and oid syntax checks that
//! MUST run before any attacker-controlled string reaches rustgit's
//! ref-store primitives (`dengel_git::refs`, re-exported verbatim from
//! the frozen rustgit spike - see lib.rs's "Trust boundary rule").
//!
//! rustgit's ref-store code is validated-input-only by design: it
//! panics on some malformed input (pack/odb.rs's read_loose_object
//! slices `&oid[0..2]` with no length check) and has NO refname syntax
//! check anywhere in src/refs/ (loose.rs defines `is_valid_oid_syntax`
//! but nothing calls it, and `loose::ref_path` is a bare
//! `git_dir.join(refname)`, which lets an absolute or `..`-laden
//! refname escape the repo entirely via PathBuf::join's documented
//! "if the pushed path is absolute, it replaces the current path"
//! behavior). This module is the gate that stops both classes of
//! input from ever reaching that code.
//!
//! Spec source for `valid_refname`: git-check-ref-format(1),
//! `Documentation/git-check-ref-format.adoc` in the git-reference
//! clean-room checkout - the ONLY C-source-adjacent reference this
//! module is allowed to consult (see CLAUDE.md's clean-room rule and
//! this milestone's brief). Every rule below is cited by its doc list
//! item. No git C source was read to write this file.

/// Is `name` a well-formed refname per git-check-ref-format(1)'s rule
/// list (the plain-ref rules, not `--refspec-pattern`)?
///
/// Rule-by-rule citation (doc list items, in the doc's own order):
///
/// 1. "no slash-separated component can begin with a dot `.` or end
///    with the sequence `.lock`"
/// 2. "They must contain at least one `/`... If the `--allow-onelevel`
///    option is used, this rule is waived." NOT ENFORCED HERE - see
///    the doc comment at the bottom of this file under "judgment
///    call: one-level names" for why, and NOTES.md's disclosure
///    entry for the confirming subprocess run.
/// 3. "cannot have two consecutive dots `..` anywhere"
/// 4. "cannot have ASCII control characters (bytes < \040, or \177
///    DEL), space, tilde `~`, caret `^`, or colon `:` anywhere"
/// 5. "cannot have question-mark `?`, asterisk `*`, or open bracket
///    `[`" (the `--refspec-pattern` exception for `*` does not apply:
///    this validator is for concrete refnames, never refspecs)
/// 6. "cannot begin or end with a slash `/` or contain multiple
///    consecutive slashes" (the `--normalize` exception does not
///    apply: this validator never rewrites input)
/// 7. "cannot end with a dot `.`"
/// 8. "cannot contain a sequence `@{`"
/// 9. "cannot be the single character `@`"
/// 10. "cannot contain a `\`"
///
/// Empty string: rejected explicitly (not a well-formed refname under
/// any git usage; also implicit from rule 6's "cannot begin... with a
/// slash" reasoning not applying, so it needs its own check).
pub fn valid_refname(name: &str) -> bool {
    if name.is_empty() {
        return false;
    }

    // Rule 9: bare "@".
    if name == "@" {
        return false;
    }

    // Rule 8: "@{" anywhere.
    if name.contains("@{") {
        return false;
    }

    // Rule 10: backslash anywhere.
    if name.contains('\\') {
        return false;
    }

    // Rule 3: ".." anywhere.
    if name.contains("..") {
        return false;
    }

    // Rule 7: cannot end with ".".
    if name.ends_with('.') {
        return false;
    }

    // Rule 6: cannot begin or end with "/", cannot contain "//".
    if name.starts_with('/') || name.ends_with('/') || name.contains("//") {
        return false;
    }

    // Rule 4 + rule 5, character-class checks over every char.
    for c in name.chars() {
        if (c as u32) < 0x20 || (c as u32) == 0x7f {
            return false; // control chars, DEL
        }
        match c {
            ' ' | '~' | '^' | ':' => return false, // rule 4
            '?' | '*' | '[' => return false,       // rule 5
            _ => {}
        }
    }

    // Rule 1: per-component leading "." / trailing ".lock".
    // (Rule 2, "must contain a slash", deliberately NOT enforced -
    // see the module-level judgment-call note below.)
    for component in name.split('/') {
        if component.starts_with('.') {
            return false;
        }
        if component.ends_with(".lock") {
            return false;
        }
    }

    true
}

/// Remote writes target loose refs. The local ref API also accepts pseudo-refs.
pub(crate) fn valid_wire_refname(name: &str) -> bool {
    name.starts_with("refs/") && valid_refname(name)
}

/// Is `s` syntactically a valid object id: exactly 40 characters, all
/// lowercase `0-9a-f`?
///
/// This guards rustgit's `pack/odb.rs::read_loose_object`, which
/// indexes `&oid[0..2]` / `&oid[2..]` on this exact string with no
/// length or char-boundary check - a string shorter than 2 bytes, or
/// one whose byte 2 falls inside a multibyte UTF-8 character, panics
/// (confirmed by the adversary role's oid_field_attacks_differential
/// probes; see g3_adversary.rs and NOTES-03.md). Checking byte length
/// and byte-wise ASCII-hex membership (never slicing) means this
/// function itself cannot panic on any input, including multibyte
/// UTF-8.
///
/// The all-zero oid ("000...0", 40 chars) is syntactically valid and
/// is accepted here - it has real meaning in delete/verify
/// preconditions and in update's documented zero-new-oid semantics
/// (git-update-ref.adoc). Semantic handling of the zero oid (e.g.
/// "create's new-oid may not be zero") stays in
/// `refs::transaction::execute_transaction`, which already implements
/// it; this function only answers the syntax question.
pub fn valid_oid(s: &str) -> bool {
    s.len() == 40
        && s.bytes()
            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}

// ---------------------------------------------------------------
// Judgment call: one-level refnames (rule 2 not enforced)
// ---------------------------------------------------------------
//
// git-check-ref-format.adoc rule 2 says a refname "must contain at
// least one `/`" UNLESS `--allow-onelevel` is passed, and states the
// default is `--no-allow-onelevel`. Read literally and applied at the
// default posture, `create HEAD <oid>` or `update HEAD <oid>` (both
// exercised by tests/g3_refstore.rs and by g3_adversary.rs's
// `head_via_update_default_deref_semantics` case, which this crate
// does not own and must not break) would be REJECTED.
//
// That contradicts real git's own observable behavior: `git
// update-ref HEAD <oid>` and single-level pseudo-refs (HEAD,
// MERGE_HEAD, FETCH_HEAD, ...) are routinely accepted by porcelain
// and plumbing alike. Confirmed directly rather than assumed, in a
// scratch subprocess (not the spike repo, per SPIKE-03 safety rules):
//
//   $ git check-ref-format HEAD                  -> exit 1
//   $ git check-ref-format --allow-onelevel HEAD  -> exit 0
//   $ git check-ref-format onelevel                    -> exit 1
//   $ git check-ref-format --allow-onelevel onelevel   -> exit 0
//
// and every OTHER case in the doc's rule list (dot-components,
// .lock, .., control chars, space/~/^/:, ?/*/[, leading/trailing/
// double slash, trailing dot, @{, bare @, backslash) produced the
// IDENTICAL exit code under both flags - `--allow-onelevel` changes
// only rule 2, nothing else. So implementing the `--allow-onelevel`
// variant uniformly (never enforcing rule 2) matches real git's
// accept/reject decision for every case this milestone's brief and
// test suite exercises, at the cost of also accepting one-level names
// outside `refs/` that real git's plain default posture would reject
// in isolation (e.g. bare `onelevel`, per g3_adversary.rs's
// `no_slash_onelevel` case). That is a floor-not-ceiling gap, not a
// security hole: rustgit's own ref_path resolution (git_dir.join(refname))
// still confines any accepted refname whose syntax is otherwise
// clean to a path under git_dir (that is the whole point of the rest
// of this gate), so a stray one-level name lands as an ordinary loose
// ref file next to HEAD, not outside the repo.
//
// Logged per CLAUDE.md's prior-knowledge-disclosure rule in
// crates/dengel-git/NOTES.md under "## G3 builder: refname validation
// disclosures".

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

    #[test]
    fn wire_refnames_stay_in_the_ref_namespace() {
        assert!(valid_wire_refname("refs/heads/main"));
        assert!(valid_wire_refname("refs/tags/v1.0"));
        assert!(!valid_wire_refname("HEAD"));
        assert!(!valid_wire_refname("metadata"));
        assert!(!valid_wire_refname("objects/local"));
    }

    // --- must-accept: ordinary names real git accepts, and this
    // --- crate's own R1-R4 suite / G1-G2 fixtures rely on. Breaking
    // --- any of these would be a real regression, not a hardening.
    const MUST_ACCEPT: &[&str] = &[
        "refs/heads/main",
        "refs/heads/stable-branch",
        "refs/tags/v1.0",
        "feature/x",
        "refs/heads/feature/nested/deep",
        "HEAD",
        "MERGE_HEAD",
        "onelevel", // judgment call: see module doc comment above
        "refs/heads/foo-bar_baz",
        "refs/heads/123",
        "refs/heads/UPPER",
    ];

    // --- must-reject: every attack case this milestone's brief and
    // --- the adversary's refname_syntax_attacks_differential /
    // --- path_escape_attacks_differential tables exercise, plus the
    // --- doc's own rule-list examples.
    const MUST_REJECT: &[&str] = &[
        "",
        "refs/heads/.hidden",      // rule 1: component begins with .
        "refs/heads/foo.lock",     // rule 1: component ends .lock
        "refs/heads/foo..bar",     // rule 3: ..
        "refs/heads/foo\u{1}bar",  // rule 4: control char (SOH)
        "refs/heads/foo\u{7f}bar", // rule 4: DEL
        "refs/heads/nul\u{0}byte", // rule 4: NUL is a control char
        "refs/heads/foo bar",      // rule 4: space
        "refs/heads/foo~bar",      // rule 4: tilde
        "refs/heads/foo^bar",      // rule 4: caret
        "refs/heads/foo:bar",      // rule 4: colon
        "refs/heads/foo?bar",      // rule 5: ?
        "refs/heads/foo*bar",      // rule 5: *
        "refs/heads/foo[bar",      // rule 5: [
        "/refs/heads/foo",         // rule 6: leading /
        "refs/heads/foo/",         // rule 6: trailing /
        "refs/heads//foo",         // rule 6: double /
        "refs/heads/foo.",         // rule 7: ends with .
        "refs/heads/foo@{bar}",    // rule 8: @{
        "@",                       // rule 9: bare @
        "refs/heads/foo\\bar",     // rule 10: backslash
        // path-escape attack cases (arbitrary-file-write finding):
        "/tmp/evil-absolute",
        "refs/heads/../../../escape",
        "refs/heads/../../outside-worktree-marker",
        "../../../etc/evil",
    ];

    #[test]
    fn accepts_legitimate_refnames() {
        for name in MUST_ACCEPT {
            assert!(valid_refname(name), "expected ACCEPT for {name:?}");
        }
    }

    #[test]
    fn rejects_attack_and_malformed_refnames() {
        for name in MUST_REJECT {
            assert!(!valid_refname(name), "expected REJECT for {name:?}");
        }
    }

    #[test]
    fn valid_oid_accepts_well_formed() {
        assert!(valid_oid(&"a".repeat(40)));
        assert!(valid_oid(&"0".repeat(40))); // zero oid: syntactically valid
        assert!(valid_oid("0123456789abcdef0123456789abcdef01234567"));
    }

    #[test]
    fn valid_oid_rejects_malformed() {
        let must_reject_oid: Vec<String> = vec![
            "".to_string(),
            "a".to_string(), // single char (odb panic probe)
            "a".repeat(39),  // 39 chars
            "a".repeat(41),  // 41 chars
            "0123456789ABCDEF0123456789abcdef01234567".to_string(), // uppercase present
            "g".repeat(40),  // non-hex
        ];
        for oid in &must_reject_oid {
            assert!(!valid_oid(oid), "expected REJECT for oid {oid:?}");
        }
        // multibyte-leading string (odb char-boundary panic probe):
        // 1 multibyte char + 39 ascii chars is 39+3=42 bytes, correctly
        // rejected by the byte-length check without ever slicing.
        let multibyte = format!("\u{4e2d}{}", "a".repeat(39));
        assert!(!valid_oid(&multibyte));
    }
}

/// Whether a packed-refs file is well-formed, by real git's standard: git
/// treats ANY unparseable line as fatal for the whole operation
/// ("unexpected line in .git/packed-refs"), rather than skipping it.
///
/// rustgit's `parse_packed_refs` is infallible and silently drops lines it
/// cannot parse - correct and fast for our own well-formed files, unsafe
/// against a poisoned one, because silently ignoring a corrupt ref line is
/// exactly the kind of wrongness that goes unnoticed for weeks (NMA-1452's
/// whole reason for slowing down here). This is the trust-boundary check
/// that runs before the ref writer acts on a repository whose packed-refs
/// it did not itself write.
///
/// Format per gitformat-signature / the packed-refs grammar observed from
/// real git: a header line starting '#'; a peel line starting '^' followed
/// by 40 hex; otherwise "<40-hex-oid> SP <refname>". Anything else is
/// malformed.
pub fn packed_refs_well_formed(content: &str) -> bool {
    for line in content.lines() {
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        if let Some(peel) = line.strip_prefix('^') {
            if !valid_oid(peel) {
                return false;
            }
            continue;
        }
        match line.split_once(' ') {
            Some((oid, refname)) if valid_oid(oid) && valid_refname(refname) => {}
            _ => return false,
        }
    }
    true
}

#[cfg(test)]
mod packed_tests {
    use super::packed_refs_well_formed;

    #[test]
    fn accepts_a_normal_packed_refs() {
        let ok = "# pack-refs with: peeled fully-peeled sorted \n\
                  cfb492f68996842205fd6f0d031b611376c0883d refs/heads/main\n\
                  ^cfb492f68996842205fd6f0d031b611376c0883d\n";
        assert!(packed_refs_well_formed(ok));
    }

    #[test]
    fn rejects_a_truncated_oid_line() {
        let bad = "# pack-refs with: peeled fully-peeled sorted \nabcd refs/heads/broken\n";
        assert!(!packed_refs_well_formed(bad));
    }

    #[test]
    fn rejects_a_line_with_no_separator() {
        let bad = "# header\ncfb492f68996842205fd6f0d031b611376c0883d\n";
        assert!(!packed_refs_well_formed(bad));
    }
}

/// Whether a ref-writer script is structurally well-formed by real git's
/// `update-ref --stdin` line rules (the non-`-z` text format): each
/// non-empty line is a known command with EXACTLY its expected field
/// count, no trailing junk, no embedded carriage returns.
///
/// rustgit's `parse_script` is deliberately lenient - it ignores fields
/// past the ones it reads and treats an all-blank script as a no-op - so a
/// script real git would reject fatally ("empty command in input", "extra
/// input") is silently accepted. For a demonstration server that is low
/// stakes (this is our own input format, not the wire), but the direction
/// is the dangerous one - accepting what canonical git rejects - so the
/// gate closes it rather than leaving a documented divergence in the ref
/// path specifically.
///
/// Returns the reason a script is malformed, or None when it is clean.
pub fn script_malformed_reason(script: &str) -> Option<String> {
    // A truly empty (zero-byte) script is a valid no-op: real git accepts
    // it (verified - `git update-ref --stdin < /dev/null` exits 0). Only a
    // script with CONTENT that parses to zero commands (whitespace, blank
    // lines) is "empty command in input". The adversary role's
    // reconciliation caught this distinction, which the first cut of the
    // gate got wrong by rejecting both.
    if script.is_empty() {
        return None;
    }
    // str::lines() consumes a trailing \r as part of the \r\n terminator,
    // so it must be caught on the raw text, not the split lines.
    if script.contains('\r') {
        return Some("carriage return in script".to_string());
    }
    let non_empty: Vec<&str> = script.lines().filter(|l| !l.is_empty()).collect();
    if non_empty.is_empty() {
        return Some("empty command in input".to_string());
    }
    for line in script.lines() {
        if line.is_empty() {
            continue;
        }
        let fields: Vec<&str> = line.split(' ').collect();
        let expected = match fields.first() {
            Some(&"create") => 3, // create <ref> <newoid>
            Some(&"update") => return check_update(&fields, line),
            Some(&"delete") => return check_1or2(&fields, line, "delete"),
            Some(&"verify") => return check_1or2(&fields, line, "verify"),
            Some(other) => return Some(format!("unsupported command {other:?}")),
            None => return Some(format!("empty command: {line:?}")),
        };
        if fields.len() != expected {
            return Some(format!("wrong field count for {}: {line:?}", fields[0]));
        }
    }
    None
}

fn check_update(fields: &[&str], line: &str) -> Option<String> {
    // update <ref> <newoid> [<oldoid>]
    if fields.len() == 3 || fields.len() == 4 {
        None
    } else {
        Some(format!("wrong field count for update: {line:?}"))
    }
}

fn check_1or2(fields: &[&str], line: &str, cmd: &str) -> Option<String> {
    // delete/verify <ref> [<oldoid>]
    if fields.len() == 2 || fields.len() == 3 {
        None
    } else {
        Some(format!("wrong field count for {cmd}: {line:?}"))
    }
}

#[cfg(test)]
mod script_edge_tests {
    use super::script_malformed_reason;

    #[test]
    fn zero_byte_script_is_valid_no_op_whitespace_only_is_not() {
        // git update-ref --stdin < /dev/null exits 0; a whitespace-only
        // body is "empty command in input". Both pinned here.
        assert_eq!(script_malformed_reason(""), None);
        assert!(script_malformed_reason("\n\n").is_some());
        assert!(script_malformed_reason("   \n").is_some());
    }
}