diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2026-01-12 21:32:38 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2026-01-12 21:33:15 +0000 |
| commit | 70c577f10bbe150b6b13bec545dc8720ad005a64 (patch) | |
| tree | 4f390cd523248db007ecb4335a61598b930ccad9 /docs/reference | |
| parent | 1948312d40f34fca868d1ef6d6d94e165c09738c (diff) | |
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
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/configuration.md | 89 |
1 files changed, 89 insertions, 0 deletions
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... | |||
| 744 | 744 | ||
| 745 | --- | 745 | --- |
| 746 | 746 | ||
| 747 | ### Repository Blacklist | ||
| 748 | |||
| 749 | #### `NGIT_REPOSITORY_BLACKLIST` | ||
| 750 | |||
| 751 | **Description:** Blacklist specific repositories/pubkeys/identifiers to reject | ||
| 752 | **Type:** Comma-separated list | ||
| 753 | **Default:** Empty (no repositories are blacklisted) | ||
| 754 | **Required:** No | ||
| 755 | |||
| 756 | **Format:** Same as whitelist formats: | ||
| 757 | - `npub1...` - Block all repos from this pubkey | ||
| 758 | - `npub1.../identifier` - Block specific repo | ||
| 759 | - `identifier` - Block repos with this identifier (any pubkey) | ||
| 760 | |||
| 761 | **Precedence:** Blacklist takes precedence over **ALL** whitelists: | ||
| 762 | - Blacklisted repos are rejected even if they match archive or repository whitelists | ||
| 763 | - Blacklisted repos are rejected even if they list our service | ||
| 764 | - Blacklist is checked **first** before any other validation | ||
| 765 | |||
| 766 | **Examples:** | ||
| 767 | |||
| 768 | ```bash | ||
| 769 | # Block all repos from specific pubkey | ||
| 770 | NGIT_REPOSITORY_BLACKLIST=npub1spam... | ||
| 771 | |||
| 772 | # Block specific repo | ||
| 773 | NGIT_REPOSITORY_BLACKLIST=npub1alice.../malware-repo | ||
| 774 | |||
| 775 | # Block repos with specific identifiers | ||
| 776 | NGIT_REPOSITORY_BLACKLIST=malware,spam,phishing | ||
| 777 | |||
| 778 | # Combined blacklist | ||
| 779 | NGIT_REPOSITORY_BLACKLIST=npub1spam...,npub1alice.../bad-repo,malware | ||
| 780 | ``` | ||
| 781 | |||
| 782 | **Rejection Reasons:** | ||
| 783 | |||
| 784 | The blacklist provides specific rejection reasons based on the match type: | ||
| 785 | |||
| 786 | - **Npub format:** `"Repository owner <npub> is blacklisted"` | ||
| 787 | - **Npub/identifier format:** `"Repository <npub>/<identifier> is blacklisted"` | ||
| 788 | - **Identifier format:** `"Repository identifier <identifier> is blacklisted"` | ||
| 789 | |||
| 790 | These reasons help operators understand why a repository was rejected without needing to flag it in curation metadata. | ||
| 791 | |||
| 792 | **Behavior:** | ||
| 793 | |||
| 794 | Blacklist is checked **before** all other validation: | ||
| 795 | 1. Check blacklist → Reject if matched | ||
| 796 | 2. Check if lists service → Accept if matches repository whitelist (if enabled) | ||
| 797 | 3. Check archive config → Accept if matches archive whitelist (if enabled) | ||
| 798 | 4. Reject otherwise | ||
| 799 | |||
| 800 | **Use Cases:** | ||
| 801 | |||
| 802 | ```bash | ||
| 803 | # Block spam/malware repos | ||
| 804 | NGIT_REPOSITORY_BLACKLIST=malware,spam,phishing | ||
| 805 | |||
| 806 | # Block abusive users | ||
| 807 | NGIT_REPOSITORY_BLACKLIST=npub1spammer...,npub1abuser... | ||
| 808 | |||
| 809 | # Block specific problematic repos | ||
| 810 | NGIT_REPOSITORY_BLACKLIST=npub1alice.../copyright-violation,npub1bob.../illegal-content | ||
| 811 | |||
| 812 | # Temporary block for investigation | ||
| 813 | NGIT_REPOSITORY_BLACKLIST=npub1suspicious.../repo-under-review | ||
| 814 | ``` | ||
| 815 | |||
| 816 | **Comparison with Whitelists:** | ||
| 817 | |||
| 818 | | Configuration | Blacklisted? | Matches Whitelist? | Lists Service? | Result | | ||
| 819 | |---------------|--------------|-------------------|----------------|---------| | ||
| 820 | | Blacklist only | Yes | N/A | N/A | ❌ Reject (blacklisted) | | ||
| 821 | | Blacklist only | No | N/A | Yes | ✅ Accept (GRASP-01) | | ||
| 822 | | Blacklist + Repository whitelist | Yes | Yes | Yes | ❌ Reject (blacklist wins) | | ||
| 823 | | Blacklist + Archive whitelist | Yes | Yes | No | ❌ Reject (blacklist wins) | | ||
| 824 | | Blacklist + Both whitelists | Yes | Yes | Yes | ❌ Reject (blacklist wins) | | ||
| 825 | | Blacklist only | No | N/A | No | ❌ Reject (no whitelist match) | | ||
| 826 | |||
| 827 | **NIP-11 Impact:** | ||
| 828 | |||
| 829 | Blacklist does **not** affect NIP-11 metadata: | ||
| 830 | - No `curation` field changes (blacklist is operational, not curation policy) | ||
| 831 | - Blacklist is transparent to clients (rejected with specific reason) | ||
| 832 | - Operators can use blacklist without advertising curation | ||
| 833 | |||
| 834 | --- | ||
| 835 | |||
| 747 | ### Logging Configuration | 836 | ### Logging Configuration |
| 748 | 837 | ||
| 749 | #### `RUST_LOG` | 838 | #### `RUST_LOG` |