mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
6a3b723eaf
After deploying a8964bb to gitnostr.com, production logs showed
event-directed proactive sync dialling ws://localhost:3334,
ws://127.0.0.1:7334, and ws://100.125.184.46:7334 (CGNAT). Repository
announcements, state events, and PR events are untrusted - anyone can
publish them - yet their relays/clone tags reached the outbound
WebSocket and git-fetch sinks after syntax-only checks, letting a
crafted event point a public relay at loopback, private, link-local,
or local-name infrastructure (SSRF).
Add one fail-closed outbound target policy (src/outbound.rs) applied
immediately before every event-directed sink so no call path can
bypass it:
- RelayConnection::connect re-authorizes (with DNS vetting) before
every dial and reconnect. SyncManager::register_relay additionally
refuses to register forbidden targets so they never enter the
reconnect lifecycle, and memoizes rejections so stored events cannot
spam logs or starve the bounded purgatory sync tick.
- RealSyncContext::fetch_oids authorizes clone URLs from announcements
and purgatory PR events immediately before spawning git fetch, then
pins the vetted DNS answers via http.curloptResolve and confines the
subprocess with GIT_ALLOW_PROTOCOL=http:https,
http.followRedirects=false, cleared proxy config/environment, and an
empty credential helper, so redirects, proxies, or alternate
protocols cannot escape the authorized target.
The policy enforces per-sink scheme allowlists (ws/wss for relays,
http/https for git), rejects embedded credentials and local hostnames
(localhost, single-label names, IANA special-use suffixes), and
requires IP literals and every DNS answer to be globally reachable.
Service admission (lists_service) and the don't-fetch-from-ourselves
filter now compare parsed host and port instead of substrings, so
gitnostr.com.attacker.example or a path containing the domain no
longer satisfies a check for gitnostr.com.
The operator-configured bootstrap relay stays usable even when local:
trust is carried by RelayTargetSource::OperatorConfigured at
construction, never by comparing event URLs against the configured
value, so event URLs that merely resemble the bootstrap relay are
still rejected. The new NGIT_SYNC_ALLOW_NON_GLOBAL_TARGETS option
(default false; documented in configuration.md, module.nix, and
.env.example) relaxes only the reachability checks for integration
tests and closed development networks; the TestRelay fixture sets it
because the test infrastructure lives on loopback, while the new
regression tests opt back into production behaviour.
Known limitation: nostr-sdk's connect API takes a URL, not a
pre-resolved address, so relay DNS is re-validated before every dial
but re-resolved by the SDK during connection, leaving a narrow
DNS-rebinding window (documented in defensive-measures.md). Git
fetches do not share this window because their DNS answers are pinned.
Closing it requires upstream connector support rather than a custom
connector here.
Validation: tests/outbound_policy.rs adds integration scenarios
against the real relay binary proving that loopback relay URLs and
loopback git clone URLs produce no outbound connection (counting TCP
listeners stand in for attacker infrastructure), that private,
link-local, CGNAT, unspecified, and multicast literals plus localhost
and credential URLs are rejected, that the local bootstrap relay still
connects while a resembling event URL is rejected, and that
substring-embedded domains are no longer admitted. src/outbound.rs
unit tests cover the reachability matrix (including 100.125.184.46)
and exact service matching. cargo fmt, cargo clippy (workspace, zero
warnings), the full cargo test suite, and cargo test -p grasp-audit
--lib all pass in the nix dev shell.
413 lines
17 KiB
Bash
413 lines
17 KiB
Bash
# ngit-grasp Configuration
|
|
#
|
|
# Configuration Priority (highest to lowest):
|
|
# 1. CLI flags (e.g., --domain example.com)
|
|
# 2. Environment variables (e.g., NGIT_DOMAIN=example.com)
|
|
# 3. This .env file
|
|
# 4. Built-in defaults
|
|
#
|
|
# Run `ngit-grasp --help` for all CLI options
|
|
|
|
# ============================================================================
|
|
# REQUIRED
|
|
# ============================================================================
|
|
|
|
# Domain where this instance is hosted (required, used in GRASP validation)
|
|
# CLI: --domain <domain>
|
|
# No default - must be set
|
|
# NGIT_DOMAIN=
|
|
|
|
# ============================================================================
|
|
# SERVER CONFIGURATION
|
|
# ============================================================================
|
|
|
|
# Server bind address (IP:PORT)
|
|
# CLI: --bind-address <address>
|
|
# Default: 127.0.0.1:7334
|
|
# NGIT_BIND_ADDRESS=127.0.0.1:7334
|
|
|
|
# ============================================================================
|
|
# RELAY INFORMATION (NIP-11)
|
|
# ============================================================================
|
|
|
|
# Relay operator's nsec (private key) for signing and authentication
|
|
# Used for:
|
|
# - NIP-11 relay information document (pubkey field derived from this nsec)
|
|
# - NIP-42 authentication when syncing from other relays
|
|
# - Future: signing events, WoT-based rate limiting of syncing relays
|
|
#
|
|
# Never accepted on the command line, so it cannot appear in process listings.
|
|
# systemd: use the relay_owner_nsec credential (highest precedence)
|
|
# Default: Loaded from/saved to .relay-owner.nsec in the current directory.
|
|
# If the file doesn't exist, a new key is generated with mode 0600.
|
|
# Empty or invalid configured values stop startup instead of rotating identity.
|
|
# NGIT_RELAY_OWNER_NSEC=nsec1...
|
|
|
|
# Relay name shown in NIP-11 information document
|
|
# CLI: --relay-name <name>
|
|
# Default: ${domain} grasp relay (e.g., "gitnostr.com grasp relay")
|
|
# NGIT_RELAY_NAME=My GRASP Relay
|
|
|
|
# Relay description shown in NIP-11 information document
|
|
# CLI: --relay-description <description>
|
|
# Default: Git Nostr Relay - a grasp implementation
|
|
# NGIT_RELAY_DESCRIPTION="A GRASP-compliant Git relay with Nostr authorization"
|
|
|
|
# ============================================================================
|
|
# STORAGE
|
|
# ============================================================================
|
|
|
|
# Path to store Git repositories
|
|
# CLI: --git-data-path <path>
|
|
# Default: ./data/git
|
|
# NGIT_GIT_DATA_PATH=./data/git
|
|
|
|
# Path to store Nostr relay data
|
|
# CLI: --relay-data-path <path>
|
|
# Default: ./data/relay
|
|
# NGIT_RELAY_DATA_PATH=./data/relay
|
|
|
|
# Database backend for Nostr events
|
|
# CLI: --database-backend <backend>
|
|
# Options: lmdb, memory
|
|
# Default: lmdb
|
|
# - lmdb: LMDB backend (persistent, general purpose) - RECOMMENDED
|
|
# - memory: In-memory database (fastest, no persistence, uses temp dirs)
|
|
#
|
|
# Note: When using 'memory' backend, git_data_path and relay_data_path
|
|
# are automatically set to temporary directories for ephemeral testing.
|
|
# NGIT_DATABASE_BACKEND=lmdb
|
|
|
|
# ============================================================================
|
|
# METRICS
|
|
# ============================================================================
|
|
|
|
# Enable Prometheus metrics endpoint at /metrics
|
|
# CLI: --metrics-enabled
|
|
# Default: true
|
|
# NGIT_METRICS_ENABLED=true
|
|
|
|
# Connections per IP before flagging as potential abuse in metrics
|
|
# (display only, no rate limiting - purely for monitoring visibility)
|
|
# CLI: --metrics-connection-per-ip-abuse-threshold <count>
|
|
# Default: 10
|
|
# NGIT_METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD=10
|
|
|
|
# Number of top bandwidth repositories to track in metrics
|
|
# CLI: --metrics-top-n-repos <count>
|
|
# Default: 10
|
|
# NGIT_METRICS_TOP_N_REPOS=10
|
|
|
|
# ============================================================================
|
|
# LOGGING
|
|
# ============================================================================
|
|
|
|
# Log level for application logging
|
|
# CLI: --log-level <level>
|
|
# Default: info
|
|
# Options: error, warn, info, debug, trace
|
|
# Can also use filter expressions: ngit_grasp=debug,actix_web=info
|
|
# NGIT_LOG_LEVEL=info
|
|
|
|
# ============================================================================
|
|
# PROACTIVE SYNC (GRASP-02)
|
|
# ============================================================================
|
|
|
|
# Bootstrap relay URL for initial sync (optional)
|
|
# Additional relays are automatically discovered from repository announcements
|
|
# that list our service domain.
|
|
# CLI: --sync-bootstrap-relay-url <url>
|
|
# Default: (none - relay discovery from stored announcements only)
|
|
# NGIT_SYNC_BOOTSTRAP_RELAY_URL=wss://relay.example.com
|
|
|
|
# Maximum backoff time in seconds for sync relay reconnection
|
|
# CLI: --sync-max-backoff-secs <seconds>
|
|
# Default: 3600 (1 hour)
|
|
# NGIT_SYNC_MAX_BACKOFF_SECS=3600
|
|
|
|
# Interval in seconds for checking disconnected relays and attempting reconnection
|
|
# Set to lower value for faster reconnection testing
|
|
# CLI: --sync-disconnect-check-interval-secs <seconds>
|
|
# Default: 60
|
|
# NGIT_SYNC_DISCONNECT_CHECK_INTERVAL_SECS=60
|
|
|
|
# Base backoff time in seconds for relay reconnection
|
|
# Used for exponential backoff: base * 2^(failures-1)
|
|
# Set to 1 for faster test cycles
|
|
# Note: The connection timeout is capped at this value
|
|
# CLI: --sync-base-backoff-secs <seconds>
|
|
# Default: 5
|
|
# NGIT_SYNC_BASE_BACKOFF_SECS=5
|
|
|
|
# Disable NIP-77 negentropy sync (use REQ+EOSE instead)
|
|
# When enabled, sync will use REQ+EOSE instead of negentropy for history sync
|
|
# Primarily useful for testing that sync works without negentropy support
|
|
# CLI: --sync-disable-negentropy
|
|
# Default: false
|
|
# NGIT_SYNC_DISABLE_NEGENTROPY=false
|
|
|
|
# Allow event-directed sync targets that are not globally reachable
|
|
# (loopback, private, link-local addresses and local hostnames). Disables the
|
|
# SSRF protection for untrusted announcement/PR relay and clone URLs; intended
|
|
# only for tests and closed development networks. The operator-configured
|
|
# bootstrap relay is always allowed regardless of this setting.
|
|
# CLI: --sync-allow-non-global-targets
|
|
# Default: false
|
|
# NGIT_SYNC_ALLOW_NON_GLOBAL_TARGETS=false
|
|
|
|
# ============================================================================
|
|
# REJECTED EVENTS INDEX
|
|
# ============================================================================
|
|
|
|
# Hot cache duration in seconds for rejected announcements
|
|
# Stores full event objects for immediate re-processing when dependencies resolve
|
|
# Too short (<30s): Miss events from slow relays
|
|
# Too long (>5min): Waste memory
|
|
# CLI: --rejected-hot-cache-duration-secs <seconds>
|
|
# Default: 120 (2 minutes)
|
|
# NGIT_REJECTED_HOT_CACHE_DURATION_SECS=120
|
|
|
|
# Cold index expiry in seconds for rejected announcements
|
|
# Stores metadata only to prevent repeated downloads of rejected events
|
|
# CLI: --rejected-cold-index-expiry-secs <seconds>
|
|
# Default: 604800 (7 days)
|
|
# NGIT_REJECTED_COLD_INDEX_EXPIRY_SECS=604800
|
|
|
|
# Hours before removing relay from naughty list
|
|
# Relays with persistent infrastructure issues (DNS, TLS, protocol errors) are
|
|
# tracked separately and retried after this expiration period
|
|
# CLI: --naughty-list-expiration-hours <hours>
|
|
# Default: 12
|
|
# NGIT_NAUGHTY_LIST_EXPIRATION_HOURS=12
|
|
|
|
# ============================================================================
|
|
# HOLDING DB AND DELETION-REQUEST CLEANUP
|
|
# ============================================================================
|
|
|
|
# Retention window in seconds for deleted events kept in holding DB
|
|
# Used by startup catch-up and periodic expiration cleanup
|
|
# Must be greater than 0
|
|
# CLI: --holding-retention-secs <seconds>
|
|
# Default: 7776000 (90 days)
|
|
# NGIT_HOLDING_RETENTION_SECS=7776000
|
|
|
|
# Interval in seconds between holding DB and deletion-request retention background
|
|
# cleanup passes. This cadence does not alter timestamp-derived retention deadlines.
|
|
# Must be greater than 0
|
|
# CLI: --holding-cleanup-interval-secs <seconds>
|
|
# Default: 86400 (24 hours)
|
|
# NGIT_HOLDING_CLEANUP_INTERVAL_SECS=86400
|
|
|
|
# ============================================================================
|
|
# 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=
|
|
|
|
# Archive GRASP services: comma-separated list of GRASP server domains to archive
|
|
# Archives all repositories from the specified GRASP server domains
|
|
# Must be bare domains only (e.g., git.example.com, NOT wss://git.example.com)
|
|
# Mutually exclusive with NGIT_ARCHIVE_ALL and NGIT_ARCHIVE_WHITELIST
|
|
# Automatically sets NGIT_ARCHIVE_READ_ONLY to true by default
|
|
# CLI: --archive-grasp-services <list>
|
|
# Default: (empty)
|
|
# Examples:
|
|
# NGIT_ARCHIVE_GRASP_SERVICES=git.example.com
|
|
# NGIT_ARCHIVE_GRASP_SERVICES=git.example.com,git.nostr.dev,relay.gitnostr.com
|
|
# NGIT_ARCHIVE_GRASP_SERVICES=
|
|
|
|
# Archive read-only mode (relay is read-only sync of archived repositories)
|
|
# When true:
|
|
# - NIP-11 includes GRASP-05 in supported_grasps
|
|
# - NIP-11 curation field describes archive scope
|
|
# - Repository announcements not listing this service are accepted per whitelist/archive-all
|
|
# When false:
|
|
# - Archive mode disabled (standard GRASP-01 operation)
|
|
#
|
|
# CLI: --archive-read-only
|
|
# Default: true if NGIT_ARCHIVE_ALL, NGIT_ARCHIVE_WHITELIST, or NGIT_ARCHIVE_GRASP_SERVICES is set, false otherwise
|
|
# Note: Setting to true without archive config causes startup error
|
|
# Note: Cannot be used with NGIT_REPOSITORY_WHITELIST (mutually exclusive)
|
|
# NGIT_ARCHIVE_READ_ONLY=
|
|
|
|
# ============================================================================
|
|
# GRASP-06 CONTRIBUTOR PR SUBMISSION
|
|
# ============================================================================
|
|
|
|
# Enable GRASP-06 contributor PR submission endpoint at /prs/<npub>/<identifier>.git
|
|
#
|
|
# When enabled, the relay exposes an unauthenticated PR submission endpoint that
|
|
# accepts pushes of refs/nostr/<event-id> from any contributor. Security relies
|
|
# on the signed PR/PR-Update events the refs reference, not on HTTP-level auth.
|
|
#
|
|
# When disabled (default), /prs/* returns 404 and event-acceptance is unchanged.
|
|
#
|
|
# See: https://github.com/DanConwayDev/grasp/blob/main/06.md
|
|
# See: docs/explanation/grasp-06-contributor-pr-submission.md
|
|
#
|
|
# CLI: --grasp06-enable
|
|
# Default: false
|
|
# NGIT_GRASP06_ENABLE=false
|
|
|
|
# ============================================================================
|
|
# DELETION REQUESTS (NIP-09 AND NIP-62)
|
|
# ============================================================================
|
|
|
|
# Deletion request disrespector: ignore NIP-09 and NIP-62 requests (archival mode)
|
|
#
|
|
# When enabled, incoming NIP-09 (kind 5) deletion requests and NIP-62
|
|
# request-to-vanish events are STORED but NOT acted upon: their targets remain
|
|
# fully accessible. This makes the relay an archival server, preserving content
|
|
# and preventing "left-pad" scenarios. NIP-11 supported_nips will NOT advertise
|
|
# NIP-09 (deletion) or NIP-62 (request to vanish) in this mode.
|
|
#
|
|
# This ONLY affects NIP-09 and NIP-62 user-initiated requests. It does NOT
|
|
# prevent blacklist-triggered deletions (operator moderation: spam/malware/abuse).
|
|
#
|
|
# When disabled (default), both request types are honoured: their targets are
|
|
# deleted and re-submission stays rejected. NIP-09 and NIP-62 are advertised in
|
|
# NIP-11.
|
|
#
|
|
# See: docs/explanation/repository-lifecycle.md
|
|
#
|
|
# CLI: --deletion-request-disrespector
|
|
# Default: false
|
|
# NGIT_DELETION_REQUEST_DISRESPECTOR=false
|
|
|
|
# Deletion-request retention applies to accepted NIP-09 deletion requests and
|
|
# NIP-62 request-to-vanish events. All values are integer seconds. Unused clocks
|
|
# start at relay-observed first_seen_at; used clocks start at last_used_at.
|
|
# "Additional" periods begin after their corresponding served period ends.
|
|
# Used requests remain served indefinitely when deletion-request-disrespector is true.
|
|
# Seconds permit short tests; production periods should be at least one day and
|
|
# comfortably exceed worst-case deletion/archive processing time.
|
|
|
|
# How long an unused request remains served from first_seen_at
|
|
# CLI: --deletion-request-retention-unused-served-secs <seconds>
|
|
# Default: 2592000 (30 days)
|
|
# NGIT_DELETION_REQUEST_RETENTION_UNUSED_SERVED_SECS=2592000
|
|
|
|
# Additional time an unused request remains unserved but eligible to gate
|
|
# CLI: --deletion-request-retention-unused-unserved-gating-additional-secs <seconds>
|
|
# Default: 15552000 (180 days)
|
|
# NGIT_DELETION_REQUEST_RETENTION_UNUSED_UNSERVED_GATING_ADDITIONAL_SECS=15552000
|
|
|
|
# Normal-mode time a used request remains served after last_used_at
|
|
# CLI: --deletion-request-retention-used-served-after-last-used-secs <seconds>
|
|
# Default: 23328000 (270 days; 9 fixed 30-day months)
|
|
# NGIT_DELETION_REQUEST_RETENTION_USED_SERVED_AFTER_LAST_USED_SECS=23328000
|
|
|
|
# Additional normal-mode time a used request remains unserved but continues gating
|
|
# CLI: --deletion-request-retention-used-unserved-gating-additional-secs <seconds>
|
|
# Default: 7776000 (90 days; 3 fixed 30-day months)
|
|
# NGIT_DELETION_REQUEST_RETENTION_USED_UNSERVED_GATING_ADDITIONAL_SECS=7776000
|
|
|
|
# ============================================================================
|
|
# REPOSITORY WHITELIST
|
|
# ============================================================================
|
|
|
|
# Whitelist specific repos/pubkeys/identifiers for GRASP-01 acceptance
|
|
# Comma-separated list supporting three formats (same as archive whitelist):
|
|
# <npub> - Accept all repos from this pubkey (if they list our service)
|
|
# <npub>/<identifier> - Accept specific repo (if it lists our service)
|
|
# <identifier> - Accept repos with this identifier (if they list our service)
|
|
#
|
|
# Difference from archive whitelist:
|
|
# - Repository whitelist: Announcements MUST list our service AND match whitelist
|
|
# - Archive whitelist: Announcements don't need to list our service, just match whitelist
|
|
#
|
|
# CLI: --repository-whitelist <list>
|
|
# Default: (empty - all repos listing our service are accepted)
|
|
# Examples:
|
|
# NGIT_REPOSITORY_WHITELIST=npub1alice...
|
|
# NGIT_REPOSITORY_WHITELIST=npub1alice...,npub1bob.../linux
|
|
# NGIT_REPOSITORY_WHITELIST=bitcoin-core,linux,rust
|
|
# Note: Cannot be used with NGIT_ARCHIVE_READ_ONLY=true (mutually exclusive)
|
|
# Note: When set, NIP-11 curation field will indicate curated repository acceptance
|
|
# NGIT_REPOSITORY_WHITELIST=
|
|
|
|
# ============================================================================
|
|
# REPOSITORY BLACKLIST
|
|
# ============================================================================
|
|
|
|
# Blacklist specific repos/pubkeys/identifiers to reject
|
|
# Comma-separated list supporting three formats (same as whitelist formats):
|
|
# <npub> - Block all repos from this pubkey
|
|
# <npub>/<identifier> - Block specific repo
|
|
# <identifier> - Block repos with this identifier (any pubkey)
|
|
#
|
|
# Blacklist takes precedence over ALL whitelists:
|
|
# - Blacklisted repos are rejected even if they match archive or repository whitelists
|
|
# - Blacklisted repos are rejected even if they list our service
|
|
#
|
|
# Rejection reasons indicate the match type:
|
|
# - "Repository owner <npub> is blacklisted" (npub format)
|
|
# - "Repository <npub>/<identifier> is blacklisted" (npub/identifier format)
|
|
# - "Repository identifier <identifier> is blacklisted" (identifier format)
|
|
#
|
|
# CLI: --repository-blacklist <list>
|
|
# Default: (empty - no repositories are blacklisted)
|
|
# Examples:
|
|
# NGIT_REPOSITORY_BLACKLIST=npub1spam...
|
|
# NGIT_REPOSITORY_BLACKLIST=npub1alice.../bad-repo
|
|
# NGIT_REPOSITORY_BLACKLIST=malware-repo,spam-repo
|
|
# NGIT_REPOSITORY_BLACKLIST=
|
|
|
|
# Automatically restore repositories that were previously deleted by blacklist
|
|
# parity when they are no longer blacklisted and still within holding retention.
|
|
# Runs once on startup as part of startup parity orchestration.
|
|
# CLI: --blacklist-auto-restore
|
|
# Default: false
|
|
# NGIT_BLACKLIST_AUTO_RESTORE=false
|
|
|
|
# ============================================================================
|
|
# EVENT BLACKLIST
|
|
# ============================================================================
|
|
|
|
# Blacklist events from specific authors (npubs)
|
|
# Comma-separated list of npubs whose events are rejected
|
|
# ALL events from these authors are blocked from both relay storage and purgatory
|
|
#
|
|
# Event blacklist takes precedence over ALL other validation:
|
|
# - Blacklisted events are rejected before any other policy checks
|
|
# - Applies to announcements, state events, PRs, and all other event types
|
|
# - Events never reach purgatory (rejected immediately)
|
|
#
|
|
# Rejection reason:
|
|
# - "Event author <npub> is blacklisted"
|
|
#
|
|
# CLI: --event-blacklist <list>
|
|
# Default: (empty - no events are blacklisted by author)
|
|
# Examples:
|
|
# NGIT_EVENT_BLACKLIST=npub1spam...
|
|
# NGIT_EVENT_BLACKLIST=npub1spam...,npub1abuser...
|
|
# NGIT_EVENT_BLACKLIST=
|
|
|
|
# ============================================================================
|
|
# RATE LIMITING & DOS PROTECTION
|
|
# ============================================================================
|
|
|
|
# Maximum total connections to the relay
|
|
# When unset (default), connections are unlimited (defers to OS fd limits and infrastructure controls)
|
|
# CLI: --max-connections <count>
|
|
# Default: unlimited
|
|
# NGIT_MAX_CONNECTIONS=4096
|