From a12927181c571fc1641772ad44dd4c6a4ab209d9 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 12 Jan 2026 20:30:13 +0000
Subject: feat(grasp-05): add read-only mode with auto-enable for archive
 configs

Implements NGIT_ARCHIVE_READ_ONLY configuration option that defaults to true
when archive mode is enabled, allowing relays to operate as read-only syncs
of archived repositories.

Key changes:
- Add NGIT_ARCHIVE_READ_ONLY config option (defaults to true if archive enabled)
- NIP-11 advertises GRASP-05 support and includes curation field when read-only
- Validation logic rejects non-whitelisted repos in read-only mode
- Comprehensive tests for read-only behavior and defaults
- Full documentation in config reference, .env.example, and NixOS module

Read-only mode enables passive mirroring without being listed in announcements,
useful for backup/archive operations while preventing accidental write acceptance.
---
 docs/reference/configuration.md | 71 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

(limited to 'docs/reference')

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 52418ad..4692600 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -574,6 +574,77 @@ NGIT_ARCHIVE_WHITELIST=npub1alice23...,npub1bob23.../linux,bitcoin-core
 
 ---
 
+#### `NGIT_ARCHIVE_READ_ONLY`
+
+**Description:** Configure relay as read-only sync of archived repositories  
+**Type:** Boolean  
+**Default:** `true` if `NGIT_ARCHIVE_ALL` or `NGIT_ARCHIVE_WHITELIST` is set, `false` otherwise  
+**Required:** No
+
+**Examples:**
+
+```bash
+# Explicitly enable (requires archive mode)
+NGIT_ARCHIVE_READ_ONLY=true
+
+# Explicitly disable (writable archive repos)
+NGIT_ARCHIVE_READ_ONLY=false
+
+# Automatic (default behavior)
+# - If NGIT_ARCHIVE_ALL or NGIT_ARCHIVE_WHITELIST is set → true
+# - Otherwise → false
+# NGIT_ARCHIVE_READ_ONLY=
+```
+
+**Behavior:**
+
+- When `true`:
+  - NIP-11 document includes `GRASP-05` in `supported_grasps`
+  - NIP-11 `curation` field describes the archive scope
+  - Repository announcements not listing this service are accepted per whitelist/archive-all
+- When `false`:
+  - Archive mode disabled (standard GRASP-01 operation)
+- When unset (default):
+  - Automatically `true` if archive mode configured
+  - Automatically `false` otherwise
+
+**Error Conditions:**
+
+```bash
+# ERROR: Cannot set read-only without archive config
+NGIT_ARCHIVE_READ_ONLY=true
+NGIT_ARCHIVE_ALL=false
+NGIT_ARCHIVE_WHITELIST=
+# → Server fails to start: "NGIT_ARCHIVE_READ_ONLY=true requires either 
+#    NGIT_ARCHIVE_ALL=true or NGIT_ARCHIVE_WHITELIST to be set"
+```
+
+**NIP-11 Impact:**
+
+When `NGIT_ARCHIVE_READ_ONLY=true`:
+- `supported_grasps`: includes `"GRASP-05"`
+- `curation`: Set to one of:
+  - `"Read-only sync of all repositories found on network"` (if `NGIT_ARCHIVE_ALL=true`)
+  - `"Read-only sync of whitelisted repositories and maintainers"` (if `NGIT_ARCHIVE_WHITELIST` set)
+
+**Use Cases:**
+
+```bash
+# Public archive of entire ecosystem
+NGIT_ARCHIVE_ALL=true
+NGIT_ARCHIVE_READ_ONLY=true  # Default
+
+# Selective backup of critical projects
+NGIT_ARCHIVE_WHITELIST=npub1torvalds.../linux,npub1satoshi.../bitcoin
+NGIT_ARCHIVE_READ_ONLY=true  # Default
+
+# Writable mirror (advanced, not typical)
+NGIT_ARCHIVE_WHITELIST=npub1alice...
+NGIT_ARCHIVE_READ_ONLY=false
+```
+
+---
+
 ### Logging Configuration
 
 #### `RUST_LOG`
-- 
cgit v1.2.3