From 2821578202d1313c23c30a5dbae39548822e3c55 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Wed, 14 Jan 2026 13:40:20 +0000 Subject: docs: add defensive measures explanation Add comprehensive documentation explaining the defensive features implemented in ngit-grasp. The detailed analysis of other relay implementations is now preserved in commit history (e3792b9). --- docs/explanation/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'docs/explanation/README.md') diff --git a/docs/explanation/README.md b/docs/explanation/README.md index f477b73..58cc46f 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md @@ -151,6 +151,48 @@ Explanation documentation helps you **understand concepts** and design decisions --- +### [Defensive Measures & Rate Limiting](defensive-measures.md) +**Protection against abuse, spam, and denial-of-service attacks** + +**Topics:** +- Connection and subscription management +- Event publishing rate limits +- Content filtering (blacklists/whitelists) +- Event validation plugin system (WritePolicy/QueryPolicy) +- Relay health management (naughty list, exponential backoff) +- Privacy-preserving IP tracking +- Future enhancements (per-IP rate limiting) + +**Read when:** You want to understand how ngit-grasp protects against abuse and what defensive features are available + +--- + +### [GRASP-05 Archive Mode](grasp-05-archive.md) +**Read-only mirroring of repositories** + +**Topics:** +- Archive whitelist configuration +- Archive-all mode +- Read-only mode defaults +- Use cases for backup/mirror relays + +**Read when:** You want to understand how to run an archive/backup relay + +--- + +### [Deletion Requests](deletion-requests.md) +**Handling repository and event deletion** + +**Topics:** +- Deletion request architecture +- Delete disrespector concept +- Preventing left-pad scenarios +- Archival policies + +**Read when:** You want to understand how ngit-grasp handles deletion events (planned feature) + +--- + ## Planned Explanation Documentation ### GRASP Protocol Design -- cgit v1.2.3