From 817ce37a5ee8d6279a44cf8cce3cc6a1e4bab576 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 12 Jan 2026 14:05:51 +0000
Subject: feat: add uploadpack.allowFilter support for GRASP-01 compliance

Add mandatory uploadpack.allowFilter capability to support partial clones
and fetches as required by GRASP-01 specification. This enables efficient
git operations for bandwidth-constrained clients (e.g., browser-based git
clients like git-natural-api).

Changes:
- Add uploadpack.allowFilter=true to git subprocess configuration
- Update SmartGitServer test helper with filter support
- Add integration tests for filter capability advertisement and functionality
- Update documentation to reflect filter as required capability

Tests verify:
- Filter capability is advertised in info/refs
- Filtered clones with blob:none work correctly
- Filtered fetches with tree:0 work correctly
---
 docs/reference/git-protocol.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'docs/reference')

diff --git a/docs/reference/git-protocol.md b/docs/reference/git-protocol.md
index 172a7bc..c0ecb3b 100644
--- a/docs/reference/git-protocol.md
+++ b/docs/reference/git-protocol.md
@@ -4,6 +4,44 @@
 
 This document explains the Git Smart HTTP protocol as it relates to our inline authorization implementation.
 
+## Required Git Capabilities
+
+### GRASP-01 Requirements (MUST)
+
+Per the [GRASP-01 specification](https://github.com/DanConwayDev/grasp/blob/main/01.md), implementations **MUST** advertise and support the following git capabilities:
+
+- **`allow-reachable-sha1-in-want`**: Allows clients to request commits reachable from any ref
+- **`allow-tip-sha1-in-want`**: Allows clients to request specific commit SHAs directly
+- **`uploadpack.allowFilter`**: Enables partial clone/fetch with `--filter` options
+
+These are essential for supporting `refs/nostr/<event-id>` (PR refs) and bandwidth-efficient partial clones.
+
+**Implementation:** `src/git/subprocess.rs:36-42`
+
+### How Capabilities are Advertised
+
+Git capabilities are advertised during the initial `GET /info/refs?service=git-upload-pack` request. The server spawns `git upload-pack --advertise-refs` with configuration flags:
+
+```bash
+git -c uploadpack.allowReachableSHA1InWant=true \
+    -c uploadpack.allowTipSHA1InWant=true \
+    -c uploadpack.allowFilter=true \
+    upload-pack --advertise-refs --stateless-rpc /path/to/repo.git
+```
+
+Clients parse the capability list from the response and only use features the server advertises.
+
+**Verification:** Test with `git ls-remote`:
+
+```bash
+GIT_TRACE_PACKET=1 git ls-remote https://ngit.danconwaydev.com/npub.../repo.git 2>&1 | grep -E "allow-|filter"
+```
+
+Expected output should include:
+```
+pkt-line: ... allow-tip-sha1-in-want allow-reachable-sha1-in-want filter ...
+```
+
 ## Protocol Flow
 
 ### Clone/Fetch (Upload Pack)
-- 
cgit v1.2.3