feat(grasp-05): implement archive mode for backup/mirror operation

Implements GRASP-05 specification for accepting repository announcements
that don't list this relay, enabling archive, mirror, and backup use cases.

Core Features:
- Three whitelist formats: <npub>, <npub>/<identifier>, <identifier>
- Archive-all mode for complete ecosystem mirrors
- Fail-fast npub validation at startup
- Read-only enforcement (archived repos reject pushes)
- Full GRASP-02 sync (git data + Nostr events)
- Dynamic archive status (no flags/metadata)

Implementation:
- Add ArchiveWhitelistEntry enum with Pubkey/Repository/Identifier variants
- Add ArchiveConfig with validation and matching logic
- Update AnnouncementResult to include AcceptArchive variant
- Refactor validate_announcement() to return AnnouncementResult with archive check
- Update AnnouncementPolicy with catch-all pattern for cleaner code
- Wire archive config through builder and policy layers

Configuration:
- NGIT_ARCHIVE_ALL: Accept all announcements (⚠️ storage risk)
- NGIT_ARCHIVE_WHITELIST: Comma-separated whitelist entries
- Updated docs, .env.example, and nix/module.nix

Testing:
- 28 unit tests for config parsing and whitelist matching
- 7 integration tests for archive mode validation
- All 296 tests passing

Validation Priority:
1. Lists our service → Accept (GRASP-01, read/write)
2. Is maintainer → AcceptMaintainer (multi-maintainer, read/write)
3. Matches archive config → AcceptArchive (GRASP-05, read-only)
4. None of above → Reject

Security Considerations:
- Archive-all mode has storage/bandwidth DoS risk
- Identifier-only format matches any pubkey (use npub/identifier for high-value)
- Invalid npubs cause startup failure (fail-fast)

Documentation:
- Concise explanation focused on rationale
- Reference docs updated with all config options
- README updated to reflect completed feature
- Removed from roadmap, added to compliance section

See docs/explanation/grasp-05-archive.md for details.

1 files changed, 25 insertions, 1 deletions

diff --git a/.env.example b/.env.example
index 6a93d78..2dc5266 100644
--- a/.env.example
+++ b/.env.example
@@ -165,4 +165,28 @@
 # tracked separately and retried after this expiration period
 # CLI: --naughty-list-expiration-hours <hours>
 # Default: 12
-# NGIT_NAUGHTY_LIST_EXPIRATION_HOURS=12
\ No newline at end of file
+# NGIT_NAUGHTY_LIST_EXPIRATION_HOURS=12
+
+# ============================================================================
+# GRASP-05 ARCHIVE MODE
+# ============================================================================
+
+# Accept all repository announcements (⚠️ WARNING: Storage/bandwidth risk)
+# When enabled, any repository can be mirrored to this relay
+# CLI: --archive-all
+# Default: false
+# NGIT_ARCHIVE_ALL=false
+
+# Whitelist specific repos/pubkeys/identifiers for archiving
+# Comma-separated list supporting three formats:
+#   <npub>              - Archive all repos from this pubkey
+#   <npub>/<identifier> - Archive specific repo
+#   <identifier>        - Archive repos with this identifier (any pubkey)
+#
+# CLI: --archive-whitelist <list>
+# Default: (empty)
+# Examples:
+#   NGIT_ARCHIVE_WHITELIST=npub1alice...
+#   NGIT_ARCHIVE_WHITELIST=npub1alice...,npub1bob.../linux
+#   NGIT_ARCHIVE_WHITELIST=bitcoin-core,linux,rust
+# NGIT_ARCHIVE_WHITELIST=
\ No newline at end of file