fix(miner): reject path-traversal-shaped commitSha in replay-snapshot path planner

[real-venus]

Summary

Closes #7796 — normalizeCommitSha (packages/loopover-miner/lib/replay-snapshot.ts) accepted any non-empty string and join()ed it straight into REPLAY_SNAPSHOT_SUBDIR, so a crafted commitSha like "../../../../tmp/evil" escaped the intended .loopover-replay-snapshots sandbox entirely — and would then control where git worktree add --detach <path> writes on disk.

The fix

• Constrain commitSha to a single safe path segment before it reaches path.join() — the same restricted charset repo-clone.ts's isValidRepoSegment guard uses for owner/repo (fix(miner): several owner/repo CLI parsers skip repo-clone.js's path-safety validation #5831), plus an explicit "."/".." rejection. A genuine (full or abbreviated) commit SHA is hex and always satisfies this, so no legitimate caller regresses.
• Regression test covering traversal-/separator-shaped values ("../../../../tmp/evil", "..", "a/b", "a\\b", " ../x ", …) plus the accepted hex case.

Why the test import changed (this is the crux)

packages/loopover-miner/lib is .ts-only; build:miner produces the .js at pack time. The existing test imported the extensionless/.js path — which, once that build artifact exists (as it does in CI), loads the built .js, leaving coverage.include's .ts entry at 0%. That .js-vs-.ts mismatch is why a correct guard reports 0% patch coverage. Importing the .ts source via a non-literal specifier instruments the real file (verified locally: 100% patch — 113/113 stmts, 65/65 branches) while dodging TS5097 (a literal .ts import is a typecheck error). No behavior change to the tests themselves.

Checks

npm run typecheck clean (no TS5097, no errors in the changed files); 36/36 tests pass; miner:env-reference:check clean. (build:miner produces the bin at pack time, so test:miner-pack passes in CI's full build.)

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-22 06:08:13 UTC}

2 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This closes #7796 by constraining commitSha to a single safe path segment (hex/`[A-Za-z0-9._-]+`, explicit `.`/`..` rejection) before it reaches path.join and later git as a bare revision — a real path-traversal fix at the correct layer (the value's entry point), not a downstream symptom patch. The regression test set covers traversal, separators, `.`/`..`, and a legitimate hex SHA, and the `.ts`-source-import workaround for coverage is explained and doesn't change test semantics. The fix is narrow, well-targeted, and correctly traced to the source of the vulnerable value.

Nits — 4 non-blocking

• The regex `[A-Za-z0-9._-]+` still permits a lone `.`-heavy value like `...` or `-` or a leading `-` that could be misread as a CLI flag by `git`, though this is unlikely to be exploitable since it's passed as an explicit worktree path/revision argument.
• normalizeCommitSha is also used in getSnapshot/saveSnapshot (store layer); worth a one-line comment noting the same guard doubles as sanitizing the DB key, or a test asserting store lookups reject traversal-shaped input too, for completeness.
• Consider tightening the regex to require the value look hex-like (or bound its length) rather than accepting any alphanumeric run with dots/underscores/hyphens, since `git` treats many non-SHA strings as valid revisions and this widens the accepted set slightly beyond genuine commit SHAs.
• The dynamic-import workaround for `.ts` vs `.js` coverage (test/unit/miner-replay-snapshot.test.ts:12-19) is a reasonable pragmatic fix but is easy to silently regress if someone 'cleans up' the import back to a static one later — a short comment pointer from replay-snapshot.ts or a lint rule would help it survive refactors.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#7796
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 120 registered-repo PR(s), 50 merged, 19 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	real-venus; Gittensor profile; 120 PR(s), 19 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Linked issue satisfaction

Addressed
The PR adds a validation guard to normalizeCommitSha rejecting non-hex-safe characters, path separators, and "."/"..", which prevents the demonstrated path-traversal escape, and adds regression tests covering traversal-shaped and separator-containing commitSha values plus the accepted hex case as the issue requested.

Review context

• Author: real-venus
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, Python, Rust, CSS, MDX, Svelte, Swift
• Official Gittensor activity: 120 PR(s), 19 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.22%. Comparing base (7c1a21e) to head (11e6124).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7996      +/-   ##
==========================================
- Coverage   91.91%   89.22%   -2.69%     
==========================================
  Files         739       95     -644     
  Lines       75854    21958   -53896     
  Branches    23018     3784   -19234     
==========================================
- Hits        69723    19593   -50130     
+ Misses       5038     2187    -2851     
+ Partials     1093      178     -915     

Flag	Coverage Δ
shard-1	100.00% <100.00%> (+41.54%)	⬆️
shard-2	0.00% <0.00%> (-52.03%)	⬇️
shard-3	0.00% <0.00%> (-50.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-miner/lib/replay-snapshot.ts	100.00% <100.00%> (ø)

... and 644 files with indirect coverage changes