preparing to build grasp-audit against git-relay

1 files changed, 513 insertions, 0 deletions

diff --git a/docs/archive/2025-11-04-evening/review-summary.md b/docs/archive/2025-11-04-evening/review-summary.md
new file mode 100644
index 0000000..29a3ff4
--- /dev/null
+++ b/docs/archive/2025-11-04-evening/review-summary.md
@@ -0,0 +1,513 @@
+# GRASP Protocol Review Summary
+
+**Date:** November 4, 2025  
+**Purpose:** Document key findings from reviewing GRASP protocol and ngit-relay
+
+---
+
+## 🎯 Critical Discoveries
+
+### 1. Single Port Architecture (CRITICAL!)
+
+**Finding:** Git server and Nostr relay MUST run on the SAME port.
+
+**Evidence:**
+```yaml
+# ../ngit-relay/docker-compose.yml
+ports:
+  - "8081:8081"  # Single port only!
+```
+
+```nginx
+# ../ngit-relay/src/nginx.conf
+server {
+    listen 8081;  # One listener for everything
+    
+    location ~ ^/npub1([a-z0-9]+)/([^/]+\.git)(/.*)?$ {
+        # Git HTTP via fcgiwrap
+    }
+    
+    location / {
+        # Nostr relay via proxy to localhost:3334
+    }
+}
+```
+
+**Impact:**
+- Our current architecture is WRONG
+- We assumed separate ports (relay on 8080, git on 8081)
+- Must use HTTP router to split traffic by path
+- actix-web can handle this
+
+**Action Required:**
+- Integrate actix-web for HTTP routing
+- Route `/<npub>/<id>.git` to Git handler
+- Route `/` to Nostr relay (WebSocket upgrade)
+- Apply CORS to ALL routes
+
+---
+
+### 2. GRASP-01 Test Requirements
+
+**Finding:** Tests must closely map to GRASP protocol specification.
+
+**GRASP-01 Requirements (from ../grasp/01.md):**
+
+#### Nostr Relay (Lines 1-14)
+- ✅ Serve NIP-01 relay at `/` (WebSocket)
+- ⏳ Accept NIP-34 repository announcements (kind 30617)
+- ⏳ Accept NIP-34 state announcements (kind 30618)
+- ⏳ Reject announcements without service in `clone` and `relays` tags
+- ⏳ Accept events that tag accepted announcements
+- ✅ Serve NIP-11 relay information
+- ⏳ Include `supported_grasps`, `repo_acceptance_criteria`, `curation` in NIP-11
+
+#### Git Smart HTTP (Lines 15-31)
+- ❌ Serve repos at `/<npub>/<identifier>.git`
+- ❌ Accept pushes matching state announcements
+- ❌ Respect recursive maintainer sets
+- ❌ Set HEAD per state announcement
+- ❌ Accept pushes to `refs/nostr/<event-id>` for PRs
+- ❌ Include `allow-reachable-sha1-in-want` and `allow-tip-sha1-in-want`
+- ❌ Serve webpage for browsers
+
+#### CORS Support (Lines 32-40)
+- ❌ `Access-Control-Allow-Origin: *` on ALL responses
+- ❌ `Access-Control-Allow-Methods: GET, POST` on ALL responses
+- ❌ `Access-Control-Allow-Headers: Content-Type` on ALL responses
+- ❌ Respond to OPTIONS with 204 No Content
+
+**Action Required:**
+- Create test for each requirement
+- Reference GRASP-01 line numbers in test comments
+- Example:
+  ```rust
+  #[tokio::test]
+  async fn test_git_http_basic() {
+      // Reference: ../grasp/01.md line 15
+      // MUST serve git repository via unauthenticated git smart http
+      // ...
+  }
+  ```
+
+---
+
+### 3. Environment Variables
+
+**Finding:** ngit-relay uses specific environment variables we should match.
+
+**From ../ngit-relay/.env.example:**
+
+```bash
+# Service Configuration
+NGIT_DOMAIN=example.com              # For announcement validation
+NGIT_INTERNAL_RELAY_PORT_FOR_SSL_PROXY=8081  # We don't need this
+
+# Relay Information (NIP-11)
+NGIT_RELAY_NAME="..."
+NGIT_RELAY_DESCRIPTION="..."
+NGIT_OWNER_NPUB="..."
+
+# Features
+NGIT_PROACTIVE_SYNC_GIT=true         # GRASP-02 (future)
+NGIT_PROACTIVE_SYNC_BLOSSOM=true     # Not in GRASP
+NGIT_PROACTIVE_SYNC_NOSTR=true       # GRASP-02 (future)
+
+# Blossom Settings
+NGIT_BLOSSOM_MAX_FILE_SIZE_MB=100    # Not in GRASP
+NGIT_BLOSSOM_MAX_CAPACITY_GB=50      # Not in GRASP
+
+# Logging
+NGIT_LOG_DIR=/var/log/ngit-relay
+NGIT_LOG_LEVEL=INFO
+NGIT_LOG_MAX_SIZE_MB=20
+NGIT_LOG_MAX_BACKUPS=10
+NGIT_LOG_MAX_AGE_DAYS=30
+```
+
+**Our Environment Variables:**
+
+```bash
+# Service Configuration
+NGIT_DOMAIN=example.com              # REQUIRED - for announcement validation
+NGIT_BIND_ADDRESS=127.0.0.1:8080    # REQUIRED - single port
+
+# Relay Information (NIP-11)
+NGIT_RELAY_NAME="ngit-grasp instance"
+NGIT_RELAY_DESCRIPTION="Rust GRASP implementation"
+NGIT_OWNER_NPUB="npub1..."
+
+# Storage Paths
+NGIT_GIT_DATA_PATH=./data/repos      # REQUIRED - where to store Git repos
+NGIT_RELAY_DATA_PATH=./data/relay    # REQUIRED - where to store events
+
+# Logging
+NGIT_LOG_LEVEL=INFO
+RUST_LOG=info                         # Standard Rust logging
+```
+
+**Action Required:**
+- Update `.env.example` with all required fields
+- Add `NGIT_GIT_DATA_PATH` to config
+- Document which fields are required vs. optional
+
+---
+
+### 4. Repository Path Structure
+
+**Finding:** Repository storage follows specific pattern.
+
+**Pattern:** `{GIT_DATA_PATH}/{npub}/{identifier}.git`
+
+**Example:**
+```
+./data/repos/
+├── npub1abc.../
+│   ├── my-project.git/
+│   │   ├── HEAD
+│   │   ├── config
+│   │   ├── objects/
+│   │   └── refs/
+│   └── another-repo.git/
+└── npub1xyz.../
+    └── their-project.git/
+```
+
+**Action Required:**
+- Create repository directory structure
+- Initialize bare repositories (`git init --bare`)
+- Set ownership/permissions correctly
+- Clean up on repository deletion
+
+---
+
+### 5. NIP-11 GRASP Fields
+
+**Finding:** NIP-11 relay information must include GRASP-specific fields.
+
+**From ../grasp/01.md lines 11-14:**
+
+```json
+{
+  "name": "ngit-grasp instance",
+  "description": "Rust GRASP implementation",
+  "pubkey": "...",
+  "contact": "...",
+  "supported_nips": [1, 11, 34],
+  "supported_grasps": ["GRASP-01"],           // NEW - array of strings
+  "repo_acceptance_criteria": "...",          // NEW - human readable
+  "curation": "WoT-based spam prevention"     // NEW - optional
+}
+```
+
+**Action Required:**
+- Add `supported_grasps` field to NIP-11 response
+- Add `repo_acceptance_criteria` field
+- Add `curation` field (optional)
+- Update NIP-11 tests to verify these fields
+
+---
+
+### 6. Announcement Validation
+
+**Finding:** Relay must validate announcements list this service.
+
+**From ../grasp/01.md lines 3-5:**
+
+> MUST reject [git repository announcements] that do not list the service 
+> in both `clone` and `relays` tags unless implementing `GRASP-05`.
+
+**NIP-34 Repository Announcement (kind 30617):**
+```json
+{
+  "kind": 30617,
+  "tags": [
+    ["d", "my-project"],           // identifier
+    ["name", "My Project"],
+    ["clone", "https://example.com/npub.../my-project.git"],
+    ["clone", "https://github.com/user/my-project"],
+    ["relays", "wss://example.com"],
+    ["relays", "wss://relay.nostr.band"]
+  ]
+}
+```
+
+**Validation Logic:**
+```rust
+fn validate_announcement(event: &Event, our_domain: &str) -> Result<()> {
+    // Check for clone tag with our domain
+    let has_clone = event.tags.iter().any(|tag| {
+        tag.kind() == TagKind::Custom("clone".into()) &&
+        tag.content().map(|c| c.contains(our_domain)).unwrap_or(false)
+    });
+    
+    // Check for relays tag with our domain
+    let has_relay = event.tags.iter().any(|tag| {
+        tag.kind() == TagKind::Custom("relays".into()) &&
+        tag.content().map(|c| c.contains(our_domain)).unwrap_or(false)
+    });
+    
+    if !has_clone || !has_relay {
+        return Err(anyhow!("Announcement must list this service in both clone and relays tags"));
+    }
+    
+    Ok(())
+}
+```
+
+**Action Required:**
+- Implement announcement validation
+- Check both `clone` and `relays` tags
+- Reject if service not listed
+- Add tests for validation
+
+---
+
+### 7. State Announcement Handling
+
+**Finding:** State announcements control repository state.
+
+**NIP-34 Repository State (kind 30618):**
+```json
+{
+  "kind": 30618,
+  "tags": [
+    ["d", "my-project"],                    // identifier
+    ["refs/heads/main", "abc123..."],       // branch → commit
+    ["refs/heads/develop", "def456..."],
+    ["HEAD", "ref: refs/heads/main"],       // symbolic ref
+    ["maintainers", "npub1...", "npub2..."] // maintainer set
+  ]
+}
+```
+
+**State Handling:**
+1. When state announcement received:
+   - Update repository HEAD if needed
+   - Store state for push validation
+   - Handle maintainer set
+
+2. When push received:
+   - Query latest state announcement
+   - Validate pusher is in maintainer set (recursive)
+   - Validate ref updates match state
+   - Accept or reject push
+
+**Action Required:**
+- Parse state announcements
+- Update repository HEAD
+- Implement push validation
+- Handle recursive maintainer sets
+
+---
+
+### 8. PR Ref Handling
+
+**Finding:** Special handling for PR refs.
+
+**From ../grasp/01.md lines 22-23:**
+
+> MUST accept pushes via this service to `refs/nostr/<event-id>` but SHOULD 
+> reject if event exists on relay listing a different tip and MAY reject based 
+> on criteria such as size, SPAM prevention, etc. SHOULD delete and MAY garbage 
+> collect these refs if no corresponding [git PR event] or [git PR update event], 
+> with a `c` tag that matches the ref tip, is accepted by relay with 20 minutes.
+
+**PR Ref Lifecycle:**
+1. Push to `refs/nostr/<event-id>`
+2. Verify PR event exists on relay
+3. Verify ref tip matches PR event `c` tag
+4. Accept push
+5. After 20 minutes, check if PR event still exists
+6. If not, delete ref and garbage collect
+
+**Action Required:**
+- Accept pushes to `refs/nostr/<event-id>`
+- Validate against PR events
+- Implement 20-minute timeout
+- Implement garbage collection
+
+---
+
+### 9. Git HTTP Protocol Details
+
+**Finding:** Must support specific Git protocol features.
+
+**From ../grasp/01.md lines 25-26:**
+
+> MUST include `allow-reachable-sha1-in-want` and `allow-tip-sha1-in-want` 
+> in advertisement and serve available oids.
+
+**Git Capabilities:**
+```
+# info/refs response must include:
+allow-reachable-sha1-in-want
+allow-tip-sha1-in-want
+```
+
+**Action Required:**
+- Configure git-http-backend to advertise these capabilities
+- Ensure Git process is configured correctly
+- Test with actual Git client
+
+---
+
+### 10. CORS Requirements
+
+**Finding:** CORS must be on ALL responses, not just some.
+
+**From ../grasp/01.md lines 32-40:**
+
+```
+1. Set `Access-Control-Allow-Origin: *` on ALL responses
+2. Set `Access-Control-Allow-Methods: GET, POST` on ALL responses
+3. Set `Access-Control-Allow-Headers: Content-Type` on ALL responses
+4. Respond to OPTIONS requests with 204 No Content
+```
+
+**Implementation:**
+```rust
+// In actix-web
+App::new()
+    .wrap(
+        Cors::default()
+            .allow_any_origin()
+            .allowed_methods(vec!["GET", "POST"])
+            .allowed_headers(vec!["Content-Type"])
+            .max_age(3600)
+    )
+    // ... routes
+```
+
+**Action Required:**
+- Add CORS middleware to actix-web
+- Verify headers on all responses
+- Handle OPTIONS requests
+- Test with browser
+
+---
+
+## 📊 Compliance Status
+
+### NIP-01 (Nostr Relay)
+- ✅ WebSocket connection
+- ✅ EVENT message handling
+- ✅ REQ subscription
+- ✅ CLOSE subscription
+- ✅ Event validation
+- ⏳ NIP-11 with GRASP fields
+
+**Status:** ~80% complete
+
+### NIP-34 (Git Announcements)
+- ✅ Store announcements (kind 30617)
+- ✅ Store state events (kind 30618)
+- ⏳ Validate announcements list this service
+- ⏳ Handle maintainer sets
+- ⏳ Accept related events
+
+**Status:** ~40% complete
+
+### GRASP-01 (Core Requirements)
+- ✅ Nostr relay at `/`
+- ❌ Git HTTP at `/<npub>/<id>.git`
+- ❌ Push validation
+- ❌ Repository provisioning
+- ❌ CORS support
+
+**Status:** ~20% complete
+
+---
+
+## 🎯 Immediate Next Steps
+
+### 1. Fix Architecture (CRITICAL)
+- [ ] Add actix-web dependencies
+- [ ] Create HTTP router module
+- [ ] Route Git paths to Git handler
+- [ ] Route `/` to Nostr relay (WebSocket)
+- [ ] Apply CORS to all routes
+
+**Estimated Time:** 2-4 hours  
+**Priority:** CRITICAL  
+**Blocker:** Nothing else can proceed without this
+
+### 2. Add Git HTTP Backend
+- [ ] Integrate git-http-backend crate
+- [ ] Create Git request handler
+- [ ] Serve from `{GIT_DATA_PATH}/{npub}/{id}.git`
+- [ ] Return 404 for missing repos
+- [ ] Test with `git clone`
+
+**Estimated Time:** 2-3 hours  
+**Priority:** HIGH  
+**Blocker:** Requires architecture fix
+
+### 3. Repository Provisioning
+- [ ] Create repos when announcements received
+- [ ] Initialize bare repositories
+- [ ] Set up directory structure
+- [ ] Handle repository deletion
+
+**Estimated Time:** 1-2 hours  
+**Priority:** HIGH  
+**Blocker:** Requires Git HTTP backend
+
+### 4. Update Tests
+- [ ] Add GRASP-01 line number references
+- [ ] Create Git HTTP tests
+- [ ] Create CORS tests
+- [ ] Update NIP-11 tests
+
+**Estimated Time:** 2-3 hours  
+**Priority:** MEDIUM  
+**Blocker:** None (can start now)
+
+---
+
+## 📚 Key Files to Reference
+
+### GRASP Protocol
+- `../grasp/01.md` - **THE SPEC** - Lines 1-40
+- `../grasp/README.md` - Overview
+- `../grasp/02.md` - GRASP-02 (future)
+- `../grasp/05.md` - GRASP-05 (future)
+
+### Reference Implementation
+- `../ngit-relay/src/nginx.conf` - **ROUTING PATTERN** - Lines 8-94
+- `../ngit-relay/docker-compose.yml` - Port configuration
+- `../ngit-relay/.env.example` - Environment variables
+- `../ngit-relay/README.md` - Architecture overview
+
+### Our Code
+- `tests/nip01_compliance.rs` - Current test approach
+- `tests/common/relay.rs` - TestRelay fixture (already correct!)
+- `src/nostr/relay.rs` - Current relay implementation
+- `src/config.rs` - Configuration (needs Git path)
+
+---
+
+## ✅ Checklist for Next Session
+
+Before starting implementation:
+- [x] Read GRASP-01 specification (../grasp/01.md)
+- [x] Review ngit-relay nginx.conf routing
+- [x] Understand single-port architecture
+- [x] Review environment variables
+- [x] Understand repository path structure
+
+Ready to implement:
+- [ ] Add actix-web dependencies to Cargo.toml
+- [ ] Create src/http/mod.rs module
+- [ ] Create src/http/git.rs handler
+- [ ] Create src/http/nostr.rs handler
+- [ ] Update src/main.rs
+- [ ] Update src/config.rs
+- [ ] Update .env.example
+- [ ] Update tests/common/relay.rs
+- [ ] Create tests/grasp01_git_http.rs
+
+---
+
+**Last Updated:** November 4, 2025  
+**Next Review:** After actix-web integration