From 70c577f10bbe150b6b13bec545dc8720ad005a64 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 12 Jan 2026 21:32:38 +0000
Subject: feat(config): add repository blacklist to block specific
 repos/npubs/identifiers

Adds NGIT_REPOSITORY_BLACKLIST option for blocking repositories, taking precedence
over all whitelists (archive and repository) to enable moderation without affecting
curation policy.

Key features:
- Three blacklist formats: <npub>, <npub>/<identifier>, <identifier>
- Blacklist checked first before any other validation
- Overrides archive whitelist and repository whitelist
- Specific rejection reasons based on match type (npub/identifier/both)
- Not flagged in NIP-11 curation (operational, not policy)

Implementation:
- Add BlacklistConfig struct with check() method returning detailed reasons
- Add NGIT_REPOSITORY_BLACKLIST config option and blacklist_config() method
- Update validate_announcement() to check blacklist first with specific reasons
- 12 new unit tests covering all blacklist behavior and precedence

Configuration synced across all four sources:
- src/config.rs: Core implementation with BlacklistConfig
- .env.example: Comprehensive documentation with examples
- docs/reference/configuration.md: Complete reference documentation
- nix/module.nix: NixOS module option with environment mapping

Testing:
- 12 new tests for blacklist functionality (config + validation)
- All 332 library tests passing
- All 38 integration tests passing

Use cases:
- Block spam/malware repos by identifier
- Block abusive users by npub
- Block specific problematic repos by npub/identifier
- Temporary blocks for investigation
---
 docs/reference/configuration.md | 89 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

(limited to 'docs/reference')

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 1c62911..b90686e 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -744,6 +744,95 @@ NGIT_REPOSITORY_WHITELIST=bitcoin-core,npub1alice...
 
 ---
 
+### Repository Blacklist
+
+#### `NGIT_REPOSITORY_BLACKLIST`
+
+**Description:** Blacklist specific repositories/pubkeys/identifiers to reject  
+**Type:** Comma-separated list  
+**Default:** Empty (no repositories are blacklisted)  
+**Required:** No
+
+**Format:** Same as whitelist formats:
+- `npub1...` - Block all repos from this pubkey
+- `npub1.../identifier` - Block specific repo
+- `identifier` - Block repos with this identifier (any pubkey)
+
+**Precedence:** Blacklist takes precedence over **ALL** whitelists:
+- Blacklisted repos are rejected even if they match archive or repository whitelists
+- Blacklisted repos are rejected even if they list our service
+- Blacklist is checked **first** before any other validation
+
+**Examples:**
+
+```bash
+# Block all repos from specific pubkey
+NGIT_REPOSITORY_BLACKLIST=npub1spam...
+
+# Block specific repo
+NGIT_REPOSITORY_BLACKLIST=npub1alice.../malware-repo
+
+# Block repos with specific identifiers
+NGIT_REPOSITORY_BLACKLIST=malware,spam,phishing
+
+# Combined blacklist
+NGIT_REPOSITORY_BLACKLIST=npub1spam...,npub1alice.../bad-repo,malware
+```
+
+**Rejection Reasons:**
+
+The blacklist provides specific rejection reasons based on the match type:
+
+- **Npub format:** `"Repository owner <npub> is blacklisted"`
+- **Npub/identifier format:** `"Repository <npub>/<identifier> is blacklisted"`
+- **Identifier format:** `"Repository identifier <identifier> is blacklisted"`
+
+These reasons help operators understand why a repository was rejected without needing to flag it in curation metadata.
+
+**Behavior:**
+
+Blacklist is checked **before** all other validation:
+1. Check blacklist → Reject if matched
+2. Check if lists service → Accept if matches repository whitelist (if enabled)
+3. Check archive config → Accept if matches archive whitelist (if enabled)
+4. Reject otherwise
+
+**Use Cases:**
+
+```bash
+# Block spam/malware repos
+NGIT_REPOSITORY_BLACKLIST=malware,spam,phishing
+
+# Block abusive users
+NGIT_REPOSITORY_BLACKLIST=npub1spammer...,npub1abuser...
+
+# Block specific problematic repos
+NGIT_REPOSITORY_BLACKLIST=npub1alice.../copyright-violation,npub1bob.../illegal-content
+
+# Temporary block for investigation
+NGIT_REPOSITORY_BLACKLIST=npub1suspicious.../repo-under-review
+```
+
+**Comparison with Whitelists:**
+
+| Configuration | Blacklisted? | Matches Whitelist? | Lists Service? | Result |
+|---------------|--------------|-------------------|----------------|---------|
+| Blacklist only | Yes | N/A | N/A | ❌ Reject (blacklisted) |
+| Blacklist only | No | N/A | Yes | ✅ Accept (GRASP-01) |
+| Blacklist + Repository whitelist | Yes | Yes | Yes | ❌ Reject (blacklist wins) |
+| Blacklist + Archive whitelist | Yes | Yes | No | ❌ Reject (blacklist wins) |
+| Blacklist + Both whitelists | Yes | Yes | Yes | ❌ Reject (blacklist wins) |
+| Blacklist only | No | N/A | No | ❌ Reject (no whitelist match) |
+
+**NIP-11 Impact:**
+
+Blacklist does **not** affect NIP-11 metadata:
+- No `curation` field changes (blacklist is operational, not curation policy)
+- Blacklist is transparent to clients (rejected with specific reason)
+- Operators can use blacklist without advertising curation
+
+---
+
 ### Logging Configuration
 
 #### `RUST_LOG`
-- 
cgit v1.2.3