From c29191b1e1239e931c575a926ec9480e594476d6 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 12 Jan 2026 17:40:25 +0000
Subject: feat(grasp-05): implement archive mode for backup/mirror operation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 docs/reference/configuration.md | 76 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

(limited to 'docs/reference')

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index bdd832f..52418ad 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -498,6 +498,82 @@ NGIT_REJECTED_COLD_INDEX_EXPIRY_SECS=1209600
 
 ---
 
+### GRASP-05 Archive Configuration
+
+These options enable archive/mirror/backup mode per the GRASP-05 specification.
+
+#### `NGIT_ARCHIVE_ALL`
+
+**Description:** Accept all repository announcements regardless of whether they list this instance  
+**Type:** Boolean  
+**Default:** `false`  
+**Required:** No
+
+**Examples:**
+
+```bash
+# Enable archive-all mode (⚠️  WARNING: Storage risk)
+NGIT_ARCHIVE_ALL=true
+
+# Disable (default - GRASP-01 strict mode)
+NGIT_ARCHIVE_ALL=false
+```
+
+**Security Warning:** When enabled, any repository can be mirrored to this relay, potentially causing storage and bandwidth exhaustion. Only enable if you have unlimited resources and trust the relay network.
+
+**Notes:**
+
+- Archived repositories are read-only (pushes rejected)
+- Full sync enabled (both git data and Nostr events)
+- Takes precedence over whitelist (accepts everything)
+
+---
+
+#### `NGIT_ARCHIVE_WHITELIST`
+
+**Description:** Comma-separated list of repositories/pubkeys/identifiers to archive  
+**Type:** String (comma-separated)  
+**Default:** (empty)  
+**Required:** No
+
+**Formats:**
+
+- `<npub>` - Archive all repos from this pubkey
+- `<npub>/<identifier>` - Archive specific repo from specific pubkey
+- `<identifier>` - Archive repos with this identifier from any pubkey
+
+**Examples:**
+
+```bash
+# Archive all repos from Alice
+NGIT_ARCHIVE_WHITELIST=npub1alice23
+
+# Archive specific repos
+NGIT_ARCHIVE_WHITELIST=npub1alice23/linux,npub1bob23/bitcoin-core
+
+# Archive by identifier (any pubkey)
+NGIT_ARCHIVE_WHITELIST=bitcoin-core,linux,rust
+
+# Mixed formats
+NGIT_ARCHIVE_WHITELIST=npub1alice23...,npub1bob23.../linux,bitcoin-core
+```
+
+**Validation:**
+
+- Npub entries are validated at startup (invalid npub = server fails to start)
+- Identifier entries accept any string
+- Whitespace is trimmed
+- Empty entries are ignored
+
+**Security Notes:**
+
+- Identifier-only format (`bitcoin-core`) matches ANY pubkey
+- Use `npub/identifier` format for high-value archives
+- Whitelist is static (restart required to change)
+- Future: Dynamic management via API
+
+---
+
 ### Logging Configuration
 
 #### `RUST_LOG`
-- 
cgit v1.2.3