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.
---
 nix/module.nix | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'nix')

diff --git a/nix/module.nix b/nix/module.nix
index 79b0e83..f82f069 100644
--- a/nix/module.nix
+++ b/nix/module.nix
@@ -177,6 +177,25 @@ let
         description = "Hours before removing relay from naughty list";
       };
 
+      archiveAll = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Enable GRASP-05 archive mode: accept all repository announcements.
+          WARNING: Storage and bandwidth risk.
+        '';
+      };
+
+      archiveWhitelist = mkOption {
+        type = types.listOf types.str;
+        default = [ ];
+        example = [ "npub1alice..." "npub1bob.../linux" "bitcoin-core" ];
+        description = ''
+          GRASP-05 archive whitelist entries.
+          Formats: <npub>, <npub>/<identifier>, <identifier>
+        '';
+      };
+
       user = mkOption {
         type = types.str;
         default = "ngit-grasp-${name}";
@@ -217,6 +236,8 @@ let
         toString cfg.rejectedColdIndexExpirySecs;
       NGIT_NAUGHTY_LIST_EXPIRATION_HOURS =
         toString cfg.naughtyListExpirationHours;
+      NGIT_ARCHIVE_ALL = toString cfg.archiveAll;
+      NGIT_ARCHIVE_WHITELIST = concatStringsSep "," cfg.archiveWhitelist;
       RUST_LOG = cfg.logLevel;
     } // optionalAttrs (cfg.relayName != null) {
       NGIT_RELAY_NAME = cfg.relayName;
-- 
cgit v1.2.3