From 2eaff5b79fed364d5eba5eb38e4b7bf76326884d Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Wed, 3 Dec 2025 11:19:40 +0000 Subject: remove docs archive --- .../2025-11-04-git-http-backend-validation.md | 247 --------------------- 1 file changed, 247 deletions(-) delete mode 100644 docs/archive/2025-11-04-evening/2025-11-04-git-http-backend-validation.md (limited to 'docs/archive/2025-11-04-evening/2025-11-04-git-http-backend-validation.md') diff --git a/docs/archive/2025-11-04-evening/2025-11-04-git-http-backend-validation.md b/docs/archive/2025-11-04-evening/2025-11-04-git-http-backend-validation.md deleted file mode 100644 index d383b9f..0000000 --- a/docs/archive/2025-11-04-evening/2025-11-04-git-http-backend-validation.md +++ /dev/null @@ -1,247 +0,0 @@ -**ARCHIVED: 2025-11-04** -**Reason:** Analysis complete, validated hybrid approach -**Outcome:** Will use git-http-backend (forked) + git2 + system git - ---- - -# Analysis Summary: git-http-backend Validation - -**Date:** 2025-11-04 -**Status:** ✅ ARCHIVED - Analysis Complete - ---- - -## TL;DR - -✅ **VALIDATED:** The hybrid approach in `current_status.md` is sound -⚠️ **CAVEAT:** Must fork/vendor `git-http-backend` crate for inline authorization -✅ **READY:** Can proceed with implementation - ---- - -## Key Findings - -### 1. git-http-backend Crate (v0.1.3) - -**What it provides:** -- ✅ Actix-web based Git Smart HTTP handlers -- ✅ Upload-pack (clone/fetch) - works as-is -- ✅ Receive-pack (push) - **needs modification** -- ✅ Info/refs advertisement -- ✅ Gzip compression support -- ✅ Streaming responses - -**What it lacks:** -- ❌ Authorization hooks (spawns git immediately) -- ❌ CORS headers (needed for web clients) -- ❌ Protocol parsing (can't inspect push data) -- ❌ Proper error handling (uses eprintln!) - -### 2. Critical Handler: git_receive_pack - -**Current flow:** -``` -Request → Validate bare repo → Spawn git → Stream response -``` - -**What we need:** -``` -Request → Validate bare repo → Parse ref updates → Validate against Nostr state → Spawn git (if authorized) → Stream response - ↑ - ADD THIS -``` - -**Can't achieve with unmodified crate!** - -### 3. Recommended Solution - -**Fork the crate and modify `git_receive_pack.rs`:** - -```rust -pub async fn git_receive_pack( - request: HttpRequest, - mut payload: Payload, - service: web::Data, - validator: web::Data, // ← ADD -) -> impl Responder { - // ... existing path resolution and bare check ... - - // Read request body - let body_data = read_and_decode_body(&mut payload, &request).await?; - - // ← ADD: Parse ref updates - let ref_updates = parse_receive_pack_request(&body_data)?; - - // ← ADD: Validate authorization - let (npub, identifier) = extract_repo_info(&request.uri().path())?; - if let Err(e) = validator.validate_push(&npub, &identifier, &ref_updates).await { - return HttpResponse::Forbidden() - .json(json!({ - "error": "unauthorized", - "message": e.to_string(), - })); - } - - // Only spawn git if authorized - let mut cmd = Command::new("git"); - cmd.arg("receive-pack"); - // ... rest of existing code ... -} -``` - ---- - -## Updated Implementation Plan - -### Phase 0: Setup (NEW) -1. Fork git-http-backend repository -2. Add as git submodule or vendor code -3. Verify existing functionality works -4. Add to Cargo.toml - -### Phase 1: Foundation -1. Add git2 dependency -2. Implement GitRepository (repo management) -3. Add protocol parsing module -4. Unit tests for both - -### Phase 2: Authorization -1. Modify git_receive_pack handler -2. Implement PushValidator -3. Integration tests for validation -4. Test unauthorized rejection - -### Phase 3: Polish -1. Add CORS headers to all handlers -2. Improve error messages -3. Add tracing instead of eprintln! -4. E2E tests with real git - ---- - -## Dependencies - -```toml -[dependencies] -# Forked git-http-backend with authorization support -git-http-backend = { git = "https://github.com/our-org/git-http-backend", branch = "ngit-grasp" } - -# Git repository management -git2 = "0.20" - -# Already have: -actix-web = "4.9" -tokio = { version = "1", features = ["full"] } -nostr-sdk = "0.43" -``` - ---- - -## Validation of current_status.md - -### ✅ Hybrid Approach - CONFIRMED -- git-http-backend for HTTP layer ✅ (with fork) -- git2 for repository management ✅ -- System git for pack operations ✅ - -### ✅ Inline Authorization - ACHIEVABLE -- Can intercept before spawning git ✅ -- Can parse ref updates ✅ -- Can validate against Nostr state ✅ -- Can return 403 with error message ✅ - -### ⚠️ Additional Requirements -- Must fork/vendor git-http-backend -- Must implement protocol parsing -- Must add CORS support -- Must improve error handling - ---- - -## Risks & Mitigations - -| Risk | Impact | Mitigation | -|------|--------|------------| -| Fork maintenance | Medium | Keep changes minimal, document well | -| Protocol parsing complexity | Medium | Use git2 or implement minimal parser | -| Performance overhead | Low | Keep validation fast (< 100ms), cache state | -| Missing edge cases | Medium | Extensive testing with real git clients | - ---- - -## Next Steps - -1. **Decision:** Fork vs. vendor git-http-backend? - - Fork: Keep upstream tracking, easier updates - - Vendor: Full control, no external dependency - - **Recommendation:** Fork (easier to contribute back) - -2. **Start Phase 0:** Set up fork - - Fork https://github.com/lazhenyi/git-http-backend - - Create branch `ngit-grasp` - - Add as git submodule - -3. **Start Phase 1:** Add git2, implement GitRepository - - Write tests first (TDD) - - Focus on bare repo creation, ref management - -4. **Add protocol parsing:** Parse ref updates from pack protocol - - Research: Can git2 help? - - Or implement minimal parser - - Unit tests for various push scenarios - -5. **Modify receive-pack:** Add authorization logic - - Integration tests for validation - - Test rejection scenarios - ---- - -## Questions for Review - -1. **Fork vs. Vendor?** - - Recommendation: Fork (can contribute back, easier updates) - -2. **Protocol parsing?** - - Option A: Use git2 if it provides parsing - - Option B: Implement minimal parser (just ref updates) - - Recommendation: Research git2 first, then decide - -3. **CORS policy?** - - Allow all origins (`*`) for now? - - Or restrict to configured domains? - - Recommendation: Start with `*`, make configurable later - -4. **Error detail?** - - How much info in 403 responses? - - Show ref updates that failed? - - Show expected vs. actual commit? - - Recommendation: Detailed errors for better DX - -5. **Performance target?** - - < 100ms for auth validation? - - Cache state events? - - Recommendation: Yes to both - ---- - -## Conclusion - -✅ **The hybrid approach is validated and sound** - -⚠️ **Must fork git-http-backend for inline authorization** - -✅ **Ready to proceed with implementation** - -**Confidence Level:** High (95%) - -The crate provides exactly what we need as a foundation. The modifications required are straightforward and well-scoped. The main work is: -1. Fork setup -2. Protocol parsing -3. Authorization integration -4. CORS and polish - -All achievable within the 4-week timeline. - ---- - -**Next:** Review this analysis, make fork vs. vendor decision, then start Phase 0. -- cgit v1.2.3